<!DOCTYPE html><html lang="en"><head>
<meta charset="utf-8">
<meta name="generator" content="ReSpec 35.6.0">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<style>
span.example-title{text-transform:none}
:is(aside,div).example,div.illegal-example{padding:.5em;margin:1em 0;position:relative;clear:both}
div.illegal-example{color:red}
div.illegal-example p{color:#000}
aside.example div.example{border-left-width:.1em;border-color:#999;background:#fff}
</style>
<style>
.issue-label{text-transform:initial}
.warning>p:first-child{margin-top:0}
.warning{padding:.5em;border-left-width:.5em;border-left-style:solid}
span.warning{padding:.1em .5em .15em}
.issue.closed span.issue-number{text-decoration:line-through}
.issue.closed span.issue-number::after{content:" (Closed)";font-size:smaller}
.warning{border-color:#f11;border-color:var(--warning-border,#f11);border-width:.2em;border-style:solid;background:#fbe9e9;background:var(--warning-bg,#fbe9e9);color:#000;color:var(--text,#000)}
.warning-title:before{content:"⚠";font-size:1.3em;float:left;padding-right:.3em;margin-top:-.3em}
li.task-list-item{list-style:none}
input.task-list-item-checkbox{margin:0 .35em .25em -1.6em;vertical-align:middle}
.issue a.respec-gh-label{padding:5px;margin:0 2px 0 2px;font-size:10px;text-transform:none;text-decoration:none;font-weight:700;border-radius:4px;position:relative;bottom:2px;border:none;display:inline-block}
</style>
<style>
dfn{cursor:pointer}
.dfn-panel{position:absolute;z-index:35;min-width:300px;max-width:500px;padding:.5em .75em;margin-top:.6em;font-family:"Helvetica Neue",sans-serif;font-size:small;background:#fff;background:var(--indextable-hover-bg,#fff);color:#000;color:var(--text,#000);box-shadow:0 1em 3em -.4em rgba(0,0,0,.3),0 0 1px 1px rgba(0,0,0,.05);box-shadow:0 1em 3em -.4em var(--tocsidebar-shadow,rgba(0,0,0,.3)),0 0 1px 1px var(--tocsidebar-shadow,rgba(0,0,0,.05));border-radius:2px}
.dfn-panel:not(.docked)>.caret{position:absolute;top:-9px}
.dfn-panel:not(.docked)>.caret::after,.dfn-panel:not(.docked)>.caret::before{content:"";position:absolute;border:10px solid transparent;border-top:0;border-bottom:10px solid #fff;border-bottom-color:var(--indextable-hover-bg,#fff);top:0}
.dfn-panel:not(.docked)>.caret::before{border-bottom:9px solid #a2a9b1;border-bottom-color:var(--indextable-hover-bg,#a2a9b1)}
.dfn-panel *{margin:0}
.dfn-panel b{display:block;color:#000;color:var(--text,#000);margin-top:.25em}
.dfn-panel ul a[href]{color:#333;color:var(--text,#333)}
.dfn-panel>div{display:flex}
.dfn-panel a.self-link{font-weight:700;margin-right:auto}
.dfn-panel .marker{padding:.1em;margin-left:.5em;border-radius:.2em;text-align:center;white-space:nowrap;font-size:90%;color:#040b1c}
.dfn-panel .marker.dfn-exported{background:#d1edfd;box-shadow:0 0 0 .125em #1ca5f940}
.dfn-panel .marker.idl-block{background:#8ccbf2;box-shadow:0 0 0 .125em #0670b161}
.dfn-panel a:not(:hover){text-decoration:none!important;border-bottom:none!important}
.dfn-panel a[href]:hover{border-bottom-width:1px}
.dfn-panel ul{padding:0}
.dfn-panel li{margin-left:1em}
.dfn-panel.docked{position:fixed;left:.5em;top:unset;bottom:2em;margin:0 auto;max-width:calc(100vw - .75em * 2 - .5em - .2em * 2);max-height:30vh;overflow:auto}
</style>
    
    
<meta name="color-scheme" content="light dark">
    
<title>Design Tokens Format Module 2025.10</title>
    
    
    
<style>

      :root {
        /* Remove watermark negatively impacting readability */
        --unofficial-watermark: none !important;
      }

      .rfc2119 {
        font-style: normal;
        font-size: 0.875em;
      }
    
</style>
  
<style id="respec-mainstyle">
@keyframes pop{
0%{transform:scale(1,1)}
25%{transform:scale(1.25,1.25);opacity:.75}
100%{transform:scale(1,1)}
}
a.internalDFN{color:inherit;border-bottom:1px solid #99c;text-decoration:none}
a.externalDFN{color:inherit;border-bottom:1px dotted #ccc;text-decoration:none}
a.bibref{text-decoration:none}
.respec-offending-element:target{animation:pop .25s ease-in-out 0s 1}
.respec-offending-element,a[href].respec-offending-element{text-decoration:red wavy underline}
@supports not (text-decoration:red wavy underline){
.respec-offending-element:not(pre){display:inline-block}
.respec-offending-element{background:url() bottom repeat-x}
}
#references :target{background:#eaf3ff;animation:pop .4s ease-in-out 0s 1}
cite .bibref{font-style:italic}
a[href].orcid{padding-left:4px;padding-right:4px}
a[href].orcid>svg{margin-bottom:-2px}
ol.tof,ul.tof{list-style:none outside none}
.caption{margin-top:.5em;font-style:italic}
#issue-summary>ul{column-count:2}
#issue-summary li{list-style:none;display:inline-block}
details.respec-tests-details{margin-left:1em;display:inline-block;vertical-align:top}
details.respec-tests-details>*{padding-right:2em}
details.respec-tests-details[open]{z-index:999999;position:absolute;border:thin solid #cad3e2;border-radius:.3em;background-color:#fff;padding-bottom:.5em}
details.respec-tests-details[open]>summary{border-bottom:thin solid #cad3e2;padding-left:1em;margin-bottom:1em;line-height:2em}
details.respec-tests-details>ul{width:100%;margin-top:-.3em}
details.respec-tests-details>li{padding-left:1em}
.self-link:hover{opacity:1;text-decoration:none;background-color:transparent}
aside.example .marker>a.self-link{color:inherit}
.header-wrapper{display:flex;align-items:baseline}
:is(h2,h3,h4,h5,h6):not(#toc>h2,#abstract>h2,#sotd>h2,.head>h2){position:relative;left:-.5em}
:is(h2,h3,h4,h5,h6):not(#toch2)+a.self-link{color:inherit;order:-1;position:relative;left:-1.1em;font-size:1rem;opacity:.5}
:is(h2,h3,h4,h5,h6)+a.self-link::before{content:"§";text-decoration:none;color:var(--heading-text)}
:is(h2,h3)+a.self-link{top:-.2em}
:is(h4,h5,h6)+a.self-link::before{color:#000}
@media (max-width:767px){
dd{margin-left:0}
}
@media print{
.removeOnSave{display:none}
}
</style>
<meta name="description" content="This document describes the technical specification for a file format to
        exchange design tokens between different tools.">
<link rel="canonical" href="https://www.designtokens.org/TR/2025.10/format/">
<style>
.hljs{--base:#fafafa;--mono-1:#383a42;--mono-2:#686b77;--mono-3:#717277;--hue-1:#0b76c5;--hue-2:#336ae3;--hue-3:#a626a4;--hue-4:#42803c;--hue-5:#ca4706;--hue-5-2:#c91243;--hue-6:#986801;--hue-6-2:#9a6a01}
@media (prefers-color-scheme:dark){
.hljs{--base:#282c34;--mono-1:#abb2bf;--mono-2:#818896;--mono-3:#5c6370;--hue-1:#56b6c2;--hue-2:#61aeee;--hue-3:#c678dd;--hue-4:#98c379;--hue-5:#e06c75;--hue-5-2:#be5046;--hue-6:#d19a66;--hue-6-2:#e6c07b}
}
.hljs{display:block;overflow-x:auto;padding:.5em;color:#383a42;color:var(--mono-1,#383a42);background:#fafafa;background:var(--base,#fafafa)}
.hljs-comment,.hljs-quote{color:#717277;color:var(--mono-3,#717277);font-style:italic}
.hljs-doctag,.hljs-formula,.hljs-keyword{color:#a626a4;color:var(--hue-3,#a626a4)}
.hljs-deletion,.hljs-name,.hljs-section,.hljs-selector-tag,.hljs-subst{color:#ca4706;color:var(--hue-5,#ca4706);font-weight:700}
.hljs-literal{color:#0b76c5;color:var(--hue-1,#0b76c5)}
.hljs-addition,.hljs-attribute,.hljs-meta-string,.hljs-regexp,.hljs-string{color:#42803c;color:var(--hue-4,#42803c)}
.hljs-built_in,.hljs-class .hljs-title{color:#9a6a01;color:var(--hue-6-2,#9a6a01)}
.hljs-attr,.hljs-number,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-pseudo,.hljs-template-variable,.hljs-type,.hljs-variable{color:#986801;color:var(--hue-6,#986801)}
.hljs-bullet,.hljs-link,.hljs-meta,.hljs-selector-id,.hljs-symbol,.hljs-title{color:#336ae3;color:var(--hue-2,#336ae3)}
.hljs-emphasis{font-style:italic}
.hljs-strong{font-weight:700}
.hljs-link{text-decoration:underline}
</style>
<style>
var:hover{text-decoration:underline;cursor:pointer}
var.respec-hl{color:var(--color,#000);background-color:var(--bg-color);box-shadow:0 0 0 2px var(--bg-color)}
@media (prefers-color-scheme:dark){
var.respec-hl{filter:saturate(.9) brightness(.9)}
}
var.respec-hl-c1{--bg-color:#f4d200}
var.respec-hl-c2{--bg-color:#ff87a2}
var.respec-hl-c3{--bg-color:#96e885}
var.respec-hl-c4{--bg-color:#3eeed2}
var.respec-hl-c5{--bg-color:#eacfb6}
var.respec-hl-c6{--bg-color:#82ddff}
var.respec-hl-c7{--bg-color:#ffbcf2}
@media print{
var.respec-hl{background:0 0;color:#000;box-shadow:unset}
}
</style>
<style>
var{position:relative;cursor:pointer}
var[data-type]::after,var[data-type]::before{position:absolute;left:50%;top:-6px;opacity:0;transition:opacity .4s;pointer-events:none}
var[data-type]::before{content:"";transform:translateX(-50%);border-width:4px 6px 0 6px;border-style:solid;border-color:transparent;border-top-color:#222}
var[data-type]::after{content:attr(data-type);transform:translateX(-50%) translateY(-100%);background:#222;text-align:center;font-family:"Dank Mono","Fira Code",monospace;font-style:normal;padding:6px;border-radius:3px;color:#daca88;text-indent:0;font-weight:400}
var[data-type]:hover::after,var[data-type]:hover::before{opacity:1}
</style>
<script id="initialUserConfig" type="application/json">{
  "specStatus": "CG-FINAL",
  "group": "design-tokens",
  "thisVersion": "https://www.designtokens.org/TR/2025.10/format/",
  "latestVersion": "https://www.designtokens.org/TR/2025.10/format/",
  "prevVersion": null,
  "edDraftURI": null,
  "editors": [
    {
      "name": "Louis Chenais",
      "url": "https://bsky.app/profile/lucho.cool"
    },
    {
      "name": "Kathleen McMahon",
      "url": "https://kathleenmcmahon.dev"
    },
    {
      "name": "Drew Powers",
      "url": "https://pow.rs"
    },
    {
      "name": "Matthew Ström-Awn",
      "url": "https://matthewstrom.com"
    },
    {
      "name": "Donna Vitan",
      "url": "https://www.donnavitan.com"
    }
  ],
  "authors": [
    {
      "name": "Daniel Banks",
      "url": "https://x.com/dbanksDesign"
    },
    {
      "name": "Mike Kamminga",
      "url": "https://x.com/mikekamminga"
    },
    {
      "name": "Ayesha Mazrana (Mazumdar)",
      "url": "https://x.com/AyeshaKMaz"
    },
    {
      "name": "James Nash",
      "url": "https://cirrus.twiddles.com"
    },
    {
      "name": "Adekunle Oduye",
      "url": "https://www.adekunleoduye.com"
    },
    {
      "name": "Kevin Powell",
      "url": "https://x.com/kevinmpowell"
    }
  ],
  "github": {
    "repoURL": "https://github.com/design-tokens/community-group",
    "branch": "main"
  },
  "tocIntroductory": true,
  "logos": [
    {
      "src": "/assets/dtcg-logo-on-color.svg",
      "url": "https://www.designtokens.org",
      "alt": "Design Tokens Community Group",
      "width": 128,
      "height": 128,
      "id": "dtcg-logo"
    }
  ],
  "publishISODate": "2025-10-28T00:00:00.000Z",
  "generatedSubtitle": "Final Community Group Report 28 October 2025"
}</script>
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2021/cg-final">
<link rel="stylesheet" media="(prefers-color-scheme: dark)" href="https://www.w3.org/StyleSheets/TR/2021/dark.css"></head>

  <body class="h-entry"><div class="head">
    <p class="logos"><a class="logo" href="https://www.designtokens.org"><img crossorigin="" alt="Design Tokens Community Group" height="128" id="dtcg-logo" src="/assets/dtcg-logo-on-color.svg" width="128">
  </a></p>
    <h1 id="title" class="title">Design Tokens Format Module 2025.10</h1> 
    <p id="w3c-state">
      <a href="https://www.w3.org/standards/types#reports">Final Community Group Report</a>
      <time class="dt-published" datetime="2025-10-28">28 October 2025</time>
    </p>
    <dl>
      <dt>This version:</dt><dd>
              <a class="u-url" href="https://www.designtokens.org/TR/2025.10/format//">https://www.designtokens.org/TR/2025.10/format/</a>
            </dd>
      <dt>Latest published version:</dt><dd>
              <a href="https://www.designtokens.org/TR/2025.10/format/">https://www.designtokens.org/TR/2025.10/format/</a>
            </dd>
      
      
      
      
      
      <dt>Editors:</dt><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://bsky.app/profile/lucho.cool">Louis Chenais</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://kathleenmcmahon.dev">Kathleen McMahon</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://pow.rs">Drew Powers</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://matthewstrom.com">Matthew Ström-Awn</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://www.donnavitan.com">Donna Vitan</a>
  </dd>
      
      <dt>Authors:</dt><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://x.com/dbanksDesign">Daniel Banks</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://x.com/mikekamminga">Mike Kamminga</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://x.com/AyeshaKMaz">Ayesha Mazrana (Mazumdar)</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://cirrus.twiddles.com">James Nash</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://www.adekunleoduye.com">Adekunle Oduye</a>
  </dd><dd class="editor p-author h-card vcard">
    <a class="u-url url p-name fn" href="https://x.com/kevinmpowell">Kevin Powell</a>
  </dd>
      <dt>Feedback:</dt><dd>
        <a href="https://github.com/design-tokens/community-group/">GitHub design-tokens/community-group</a>
        (<a href="https://github.com/design-tokens/community-group/pulls/">pull requests</a>,
        <a href="https://github.com/design-tokens/community-group/issues/new/choose">new issue</a>,
        <a href="https://github.com/design-tokens/community-group/issues/">open issues</a>)
      </dd>
      
    </dl>
    
    
   <p class="copyright">
          <a href="https://www.w3.org/policies/#copyright">Copyright</a>
          ©
          2025
          
          the Contributors to the Design Tokens Resolver Module 2025.10
          Specification, published by the
          <a href="https://www.w3.org/groups/cg/design-tokens">Design Tokens Community Group</a> under the
          <a href="https://www.w3.org/community/about/agreements/fsa/">W3C Community Final Specification Agreement (FSA)</a>. A human-readable
                <a href="https://www.w3.org/community/about/agreements/fsa-deed/">summary</a>
                is available.
              
        </p>
    <hr title="Separator for header">
  </div>
    

    <section id="abstract" class="introductory"><h2>Abstract</h2>
      <p>
        This document describes the technical specification for a file format to
        exchange design tokens between different tools.
      </p>
    </section>

    <section id="sotd" class="introductory"><h2>Status of This Document</h2><p>
      This specification was published by the
      <a href="https://www.w3.org/groups/cg/design-tokens">Design Tokens Community Group</a>. It is not a W3C Standard nor is it
      on the W3C Standards Track.
      
            Please note that under the
            <a href="https://www.w3.org/community/about/agreements/final/">W3C Community Final Specification Agreement (FSA)</a>
            other conditions apply.
          
      Learn more about
      <a href="https://www.w3.org/community/">W3C Community and Business Groups</a>.
    </p>
      <p>
        This section describes the status of this document at the time of its
        publication. Other documents may supersede this document. A list of
        current W3C Community Group reports and the latest revision of this
        report can be found in the W3C Community Group reports index at
        <a href="https://www.w3.org/community/reports/">https://www.w3.org/community/reports/</a>.
      </p>
      <p>
        This document was published by the DTCG as a
        <a href="https://www.w3.org/policies/process/#RecsCR">Candidate Recommendation</a>
        following the definitions provided by the W3C process. Contributions to
        this draft are governed by
        <a href="https://www.w3.org/community/about/process/cla">
          Community Contributor License Agreement (CLA)</a>, as specified by the
        <a href="https://www.w3.org/community/about/process/#cgroups">W3C Community Group Process</a>.
      </p>
      <p>
        While not a W3C recommendation, this classification is intended to
        clarify that, after extensive consensus-building, this specification is
        intended for implementation.
      </p>
      <p>
        <strong>This specification is considered stable</strong>. Further
        updates will be provided in superseding specifications.
      </p>
    <p>
    <a href="https://github.com/design-tokens/community-group/issues/">GitHub Issues</a> are preferred for
          discussion of this specification.
        
    
  </p></section><nav id="toc"><h2 class="introductory" id="table-of-contents">Table of Contents</h2><ol class="toc"><li class="tocline"><a class="tocxref" href="#abstract">Abstract</a></li><li class="tocline"><a class="tocxref" href="#sotd">Status of This Document</a></li><li class="tocline"><a class="tocxref" href="#conformance"><bdi class="secno">1. </bdi>Conformance</a></li><li class="tocline"><a class="tocxref" href="#introduction"><bdi class="secno">2. </bdi>Introduction</a></li><li class="tocline"><a class="tocxref" href="#terminology"><bdi class="secno">3. </bdi>Terminology</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#design-token"><bdi class="secno">3.1 </bdi>(Design) Token</a></li><li class="tocline"><a class="tocxref" href="#design-token-properties"><bdi class="secno">3.2 </bdi>(Design) Token Properties</a></li><li class="tocline"><a class="tocxref" href="#design-tool"><bdi class="secno">3.3 </bdi><span data-plurals="design tools">Design tool</span></a></li><li class="tocline"><a class="tocxref" href="#translation-tool"><bdi class="secno">3.4 </bdi><span data-plurals="translation tools">Translation tool</span></a></li><li class="tocline"><a class="tocxref" href="#documentation-tool"><bdi class="secno">3.5 </bdi><span data-plurals="documentation tools">Documentation tool</span></a></li><li class="tocline"><a class="tocxref" href="#type"><bdi class="secno">3.6 </bdi>Type</a></li><li class="tocline"><a class="tocxref" href="#group"><bdi class="secno">3.7 </bdi>Group</a></li><li class="tocline"><a class="tocxref" href="#alias-reference"><bdi class="secno">3.8 </bdi>Alias (Reference)</a></li><li class="tocline"><a class="tocxref" href="#composite-design-token"><bdi class="secno">3.9 </bdi>Composite (Design) Token</a></li></ol></li><li class="tocline"><a class="tocxref" href="#file-format"><bdi class="secno">4. </bdi>File format</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#media-type-mime-type"><bdi class="secno">4.1 </bdi>Media type (MIME type)</a></li><li class="tocline"><a class="tocxref" href="#file-extensions"><bdi class="secno">4.2 </bdi>File extensions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#design-token-0"><bdi class="secno">5. </bdi>Design token</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#name-and-value"><bdi class="secno">5.1 </bdi>Name and value</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#character-restrictions"><bdi class="secno">5.1.1 </bdi>Character restrictions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#additional-properties"><bdi class="secno">5.2 </bdi>Additional properties</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#description"><bdi class="secno">5.2.1 </bdi>Description</a></li><li class="tocline"><a class="tocxref" href="#type-0"><bdi class="secno">5.2.2 </bdi>Type</a></li><li class="tocline"><a class="tocxref" href="#extensions"><bdi class="secno">5.2.3 </bdi>Extensions</a></li><li class="tocline"><a class="tocxref" href="#deprecated"><bdi class="secno">5.2.4 </bdi>Deprecated</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#groups"><bdi class="secno">6. </bdi>Groups</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#group-structure"><bdi class="secno">6.1 </bdi>Group Structure</a></li><li class="tocline"><a class="tocxref" href="#root-tokens-in-groups"><bdi class="secno">6.2 </bdi>Root Tokens in Groups</a></li><li class="tocline"><a class="tocxref" href="#group-properties"><bdi class="secno">6.3 </bdi>Group Properties</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#deprecated-0"><bdi class="secno">6.3.1 </bdi><code>$deprecated</code></a></li><li class="tocline"><a class="tocxref" href="#extensions-0"><bdi class="secno">6.3.2 </bdi><code>$extensions</code></a></li></ol></li><li class="tocline"><a class="tocxref" href="#extending-groups"><bdi class="secno">6.4 </bdi>Extending Groups</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#equivalence-to-json-schema-ref"><bdi class="secno">6.4.1 </bdi>Equivalence to JSON Schema <code>$ref</code></a></li><li class="tocline"><a class="tocxref" href="#reference-resolution-and-evaluation"><bdi class="secno">6.4.2 </bdi>Reference Resolution and Evaluation</a></li><li class="tocline"><a class="tocxref" href="#inheritance-semantics"><bdi class="secno">6.4.3 </bdi>Inheritance Semantics</a></li><li class="tocline"><a class="tocxref" href="#circular-reference-prevention"><bdi class="secno">6.4.4 </bdi>Circular Reference Prevention</a></li><li class="tocline"><a class="tocxref" href="#supported-reference-formats"><bdi class="secno">6.4.5 </bdi>Supported Reference Formats</a></li><li class="tocline"><a class="tocxref" href="#error-conditions"><bdi class="secno">6.4.6 </bdi>Error Conditions</a></li><li class="tocline"><a class="tocxref" href="#implementation-guidance"><bdi class="secno">6.4.7 </bdi>Implementation Guidance</a></li><li class="tocline"><a class="tocxref" href="#relationship-to-json-schema-specifications"><bdi class="secno">6.4.8 </bdi>Relationship to JSON Schema Specifications</a></li></ol></li><li class="tocline"><a class="tocxref" href="#empty-groups"><bdi class="secno">6.5 </bdi>Empty Groups</a></li><li class="tocline"><a class="tocxref" href="#references-and-json-pointer-integration"><bdi class="secno">6.6 </bdi>References and JSON Pointer Integration</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#current-reference-syntax-recommended"><bdi class="secno">6.6.1 </bdi>Current Reference Syntax (Recommended)</a></li><li class="tocline"><a class="tocxref" href="#json-pointer-support"><bdi class="secno">6.6.2 </bdi>JSON Pointer Support</a></li></ol></li><li class="tocline"><a class="tocxref" href="#processing-rules"><bdi class="secno">6.7 </bdi>Processing Rules</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#token-resolution-order"><bdi class="secno">6.7.1 </bdi>Token Resolution Order</a></li><li class="tocline"><a class="tocxref" href="#path-construction"><bdi class="secno">6.7.2 </bdi>Path Construction</a></li><li class="tocline"><a class="tocxref" href="#type-inheritance"><bdi class="secno">6.7.3 </bdi>Type Inheritance</a></li><li class="tocline"><a class="tocxref" href="#circular-reference-detection"><bdi class="secno">6.7.4 </bdi>Circular Reference Detection</a></li></ol></li><li class="tocline"><a class="tocxref" href="#migration-and-compatibility"><bdi class="secno">6.8 </bdi>Migration and Compatibility</a></li><li class="tocline"><a class="tocxref" href="#examples"><bdi class="secno">6.9 </bdi>Examples</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#basic-group-with-root-token"><bdi class="secno">6.9.1 </bdi>Basic Group with Root Token</a></li><li class="tocline"><a class="tocxref" href="#group-extension-with-override-example"><bdi class="secno">6.9.2 </bdi>Group Extension with Override Example</a></li><li class="tocline"><a class="tocxref" href="#complex-hierarchical-structure"><bdi class="secno">6.9.3 </bdi>Complex Hierarchical Structure</a></li></ol></li><li class="tocline"><a class="tocxref" href="#use-cases"><bdi class="secno">6.10 </bdi>Use-cases</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#file-authoring-organization"><bdi class="secno">6.10.1 </bdi>File authoring &amp; organization</a></li><li class="tocline"><a class="tocxref" href="#gui-tools"><bdi class="secno">6.10.2 </bdi>GUI tools</a></li><li class="tocline"><a class="tocxref" href="#translation-tools"><bdi class="secno">6.10.3 </bdi>Translation tools</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#aliases-references"><bdi class="secno">7. </bdi>Aliases / References</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#reference-syntax"><bdi class="secno">7.1 </bdi>Reference Syntax</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#curly-brace-syntax-token-references"><bdi class="secno">7.1.1 </bdi>Curly Brace Syntax (Token References)</a></li><li class="tocline"><a class="tocxref" href="#json-pointer-syntax-required-support"><bdi class="secno">7.1.2 </bdi>JSON Pointer Syntax (Required Support)</a></li></ol></li><li class="tocline"><a class="tocxref" href="#reference-resolution"><bdi class="secno">7.2 </bdi>Reference Resolution</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#resolution-algorithms"><bdi class="secno">7.2.1 </bdi>Resolution Algorithms</a></li><li class="tocline"><a class="tocxref" href="#chained-references"><bdi class="secno">7.2.2 </bdi>Chained References</a></li><li class="tocline"><a class="tocxref" href="#circular-references"><bdi class="secno">7.2.3 </bdi>Circular References</a></li></ol></li><li class="tocline"><a class="tocxref" href="#property-level-references"><bdi class="secno">7.3 </bdi>Property-Level References</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#color-component-references"><bdi class="secno">7.3.1 </bdi>Color Component References</a></li><li class="tocline"><a class="tocxref" href="#dimension-component-references"><bdi class="secno">7.3.2 </bdi>Dimension Component References</a></li><li class="tocline"><a class="tocxref" href="#typography-component-references"><bdi class="secno">7.3.3 </bdi>Typography Component References</a></li></ol></li><li class="tocline"><a class="tocxref" href="#json-pointer-path-construction-and-resolution"><bdi class="secno">7.4 </bdi>JSON Pointer Path Construction and Resolution</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#path-construction-rules"><bdi class="secno">7.4.1 </bdi>Path Construction Rules</a></li><li class="tocline"><a class="tocxref" href="#token-value-access-patterns"><bdi class="secno">7.4.2 </bdi>Token Value Access Patterns</a></li><li class="tocline"><a class="tocxref" href="#resolution-algorithm-for-json-pointer"><bdi class="secno">7.4.3 </bdi>Resolution Algorithm for JSON Pointer</a></li><li class="tocline"><a class="tocxref" href="#curly-brace-resolution-algorithm"><bdi class="secno">7.4.4 </bdi>Curly Brace Resolution Algorithm</a></li><li class="tocline"><a class="tocxref" href="#error-conditions-0"><bdi class="secno">7.4.5 </bdi>Error Conditions</a></li><li class="tocline"><a class="tocxref" href="#path-examples"><bdi class="secno">7.4.6 </bdi>Path Examples</a></li></ol></li><li class="tocline"><a class="tocxref" href="#implementation-guidance-0"><bdi class="secno">7.5 </bdi>Implementation Guidance</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#for-tool-authors"><bdi class="secno">7.5.1 </bdi>For Tool Authors</a></li><li class="tocline"><a class="tocxref" href="#disambiguation-examples"><bdi class="secno">7.5.2 </bdi>Disambiguation Examples</a></li><li class="tocline"><a class="tocxref" href="#error-conditions-1"><bdi class="secno">7.5.3 </bdi>Error Conditions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#relationship-to-json-schema"><bdi class="secno">7.6 </bdi>Relationship to JSON Schema</a></li></ol></li><li class="tocline"><a class="tocxref" href="#types"><bdi class="secno">8. </bdi>Types</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#color"><bdi class="secno">8.1 </bdi>Color</a></li><li class="tocline"><a class="tocxref" href="#dimension"><bdi class="secno">8.2 </bdi>Dimension</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#validation"><bdi class="secno">8.2.1 </bdi>Validation</a></li></ol></li><li class="tocline"><a class="tocxref" href="#font-family"><bdi class="secno">8.3 </bdi>Font family</a></li><li class="tocline"><a class="tocxref" href="#font-weight"><bdi class="secno">8.4 </bdi>Font weight</a></li><li class="tocline"><a class="tocxref" href="#duration"><bdi class="secno">8.5 </bdi>Duration</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#validation-0"><bdi class="secno">8.5.1 </bdi>Validation</a></li></ol></li><li class="tocline"><a class="tocxref" href="#cubic-bezier"><bdi class="secno">8.6 </bdi>Cubic Bézier</a></li><li class="tocline"><a class="tocxref" href="#number"><bdi class="secno">8.7 </bdi>Number</a></li><li class="tocline"><a class="tocxref" href="#additional-types"><bdi class="secno">8.8 </bdi>Additional types</a></li></ol></li><li class="tocline"><a class="tocxref" href="#composite-types"><bdi class="secno">9. </bdi>Composite types</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#array-aliasing-in-composite-types"><bdi class="secno">9.1 </bdi>Array aliasing in composite types</a></li><li class="tocline"><a class="tocxref" href="#groups-versus-composite-tokens"><bdi class="secno">9.2 </bdi>Groups versus composite tokens</a></li><li class="tocline"><a class="tocxref" href="#stroke-style"><bdi class="secno">9.3 </bdi>Stroke style</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#string-value"><bdi class="secno">9.3.1 </bdi>String value</a></li><li class="tocline"><a class="tocxref" href="#object-value"><bdi class="secno">9.3.2 </bdi>Object value</a></li><li class="tocline"><a class="tocxref" href="#fallbacks"><bdi class="secno">9.3.3 </bdi>Fallbacks</a></li></ol></li><li class="tocline"><a class="tocxref" href="#border"><bdi class="secno">9.4 </bdi>Border</a></li><li class="tocline"><a class="tocxref" href="#transition"><bdi class="secno">9.5 </bdi>Transition</a></li><li class="tocline"><a class="tocxref" href="#shadow"><bdi class="secno">9.6 </bdi>Shadow</a></li><li class="tocline"><a class="tocxref" href="#gradient"><bdi class="secno">9.7 </bdi>Gradient</a></li><li class="tocline"><a class="tocxref" href="#typography"><bdi class="secno">9.8 </bdi>Typography</a></li></ol></li><li class="tocline"><a class="tocxref" href="#issue-summary"><bdi class="secno">A. </bdi>Issue summary</a></li><li class="tocline"><a class="tocxref" href="#references"><bdi class="secno">B. </bdi>References</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><bdi class="secno">B.1 </bdi>Normative references</a></li></ol></li></ol></nav>

    <section id="conformance"><div class="header-wrapper"><h2 id="x1-conformance"><bdi class="secno">1. </bdi>Conformance</h2><a class="self-link" href="#conformance" aria-label="Permalink for Section 1."></a></div><p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p><p>
        The key words <em class="rfc2119">MAY</em>, <em class="rfc2119">MUST</em>, <em class="rfc2119">MUST NOT</em>, <em class="rfc2119">SHOULD</em>, and <em class="rfc2119">SHOULD NOT</em> in this document
        are to be interpreted as described in
        <a href="https://www.rfc-editor.org/info/bcp14">BCP 14</a>
        [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc2119" title="Key words for use in RFCs to Indicate Requirement Levels">RFC2119</a></cite>] [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc8174" title="Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words">RFC8174</a></cite>]
        when, and only when, they appear in all
        capitals, as shown here.
      </p></section>

    <section id="introduction"><div class="header-wrapper"><h2 id="x2-introduction"><bdi class="secno">2. </bdi>Introduction</h2><a class="self-link" href="#introduction" aria-label="Permalink for Section 2."></a></div>
      

      <p>
        <em>This section is non-normative.</em>
      </p>
      <p>
        Design tokens are a methodology for expressing design decisions in a
        platform-agnostic way so that they can be shared across different
        disciplines, tools, and technologies. They help establish a common
        vocabulary across organizations.
      </p>
      <p>
        There is a growing ecosystem of tools for design system maintainers and
        consumers that incorporate design token functionality, or would benefit
        from doing so:
      </p>
      <ul>
        <li>
          <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-1">Design tools</a> have begun allowing designers to label and reference
          shared values for design properties like colors and sizes.
        </li>
        <li>
          <a data-link-type="dfn|abstract-op" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-1">Translation tools</a> exist that can convert source design token data
          into platform-specific source code that can directly be used by
          developers.
        </li>
        <li>
          <a data-link-type="dfn|abstract-op" href="#dfn-documentation-tool" class="internalDFN" id="ref-for-dfn-documentation-tool-1">Documentation tools</a> can display design token names rather than the
          raw values in design specs and style guides.
        </li>
      </ul>
      <p>
        It is often desirable for design system teams to integrate such tools
        together, so that design token data can flow between design and
        development tools.
      </p>
      <p>For example:</p>
      <ul>
        <li>
          Extracting design tokens from design files and feeding them into
          <a data-link-type="dfn|abstract-op" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-2">translation tools</a> to then be converted into platform-specific code
        </li>
        <li>
          Maintaining a "single source of truth" for design tokens and
          automatically keeping design and development tools in sync with it
        </li>
      </ul>
      <p>
        While many tools now offer APIs to access design tokens or the ability
        to export design tokens as a file, these are all tool-specific. The
        burden is therefore on design system teams to create and maintain their
        own, bespoke "glue" code or workflows. Furthermore, if teams want to
        migrate to different tools, they will need to update those integrations.
      </p>
      <p>
        This specification aims to facilitate better interoperability between
        tools and thus lower the work design system teams need to do to
        integrate them by defining a standard file format for expressing design
        token data.
      </p>
    </section>

    <section id="terminology"><div class="header-wrapper"><h2 id="x3-terminology"><bdi class="secno">3. </bdi>Terminology</h2><a class="self-link" href="#terminology" aria-label="Permalink for Section 3."></a></div>
<p>These definitions are focused on the technical aspects of the specification, aimed at implementers such as <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-2">design tool</a> vendors. Definitions for designers and developers are available at <a href="https://www.designtokens.org/glossary/">designtokens.org</a>.</p>
<section id="design-token"><div class="header-wrapper"><h3 id="x3-1-design-token"><bdi class="secno">3.1 </bdi>(Design) Token</h3><a class="self-link" href="#design-token" aria-label="Permalink for Section 3.1"></a></div>
<p>A (Design) Token is information associated with a human readable name, at minimum a name/value pair.</p>
<p>For example:</p>
<ul>
<li><code>color-text-primary: #000000;</code></li>
<li><code>font-size-heading-level-1: 44px;</code></li>
</ul>
<p>The name may be associated with additional <a href="#design-token-properties">Token Properties</a>.</p>
</section><section id="design-token-properties-0"><div class="header-wrapper"><h3 id="design-token-properties"><bdi class="secno">3.2 </bdi>(Design) Token Properties</h3><a class="self-link" href="#design-token-properties" aria-label="Permalink for Section 3.2"></a></div>

<p>Information associated with a token name.</p>
<p>For example:</p>
<ul>
<li>Value</li>
<li>Type</li>
<li>Description</li>
</ul>
<p>Additional metadata may be added by tools and design systems to extend the format as needed.</p>
</section><section id="design-tool"><div class="header-wrapper"><h3 id="x3-3-design-tool"><bdi class="secno">3.3 </bdi><dfn data-plurals="design tools" id="dfn-design-tool" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Design tool</dfn></h3><a class="self-link" href="#design-tool" aria-label="Permalink for Section 3.3"></a></div>
<p>A design tool is a tool for visual design creation and editing.</p>
<p>For example:</p>
<ul>
<li>Bitmap image manipulation programs:<ul>
<li><a href="https://www.adobe.com/products/photoshop.html">Photoshop</a></li>
<li><a href="https://affinity.serif.com/photo">Affinity Photo</a></li>
<li><a href="https://www.getpaint.net/">Paint.net</a></li>
</ul>
</li>
<li>Vector graphics tools:<ul>
<li><a href="https://www.adobe.com/products/illustrator.html">Illustrator</a></li>
<li><a href="https://inkscape.org/">Inkscape</a></li>
</ul>
</li>
<li>UI design, wireframing and prototyping tools:<ul>
<li><a href="https://www.adobe.com/products/xd.html">Adobe XD</a></li>
<li><a href="https://www.uxpin.com/">UXPin</a></li>
<li><a href="https://www.sketch.com/">Sketch</a></li>
<li><a href="https://www.figma.com/">Figma</a></li>
<li>...</li>
</ul>
</li>
</ul>
</section><section id="translation-tool"><div class="header-wrapper"><h3 id="x3-4-translation-tool"><bdi class="secno">3.4 </bdi><dfn data-plurals="translation tools" id="dfn-translation-tool" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Translation tool</dfn></h3><a class="self-link" href="#translation-tool" aria-label="Permalink for Section 3.4"></a></div>
<p>Design token translation tools translate token data from one format to another.</p>
<p>For example:</p>
<ul>
<li><a href="https://amzn.github.io/style-dictionary/">Style Dictionary</a></li>
<li><a href="https://github.com/terrazzoapp/terrazzo">Terrazzo</a></li>
<li>...</li>
</ul>
</section><section id="documentation-tool"><div class="header-wrapper"><h3 id="x3-5-documentation-tool"><bdi class="secno">3.5 </bdi><dfn data-plurals="documentation tools" id="dfn-documentation-tool" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Documentation tool</dfn></h3><a class="self-link" href="#documentation-tool" aria-label="Permalink for Section 3.5"></a></div>
<p>A documentation tool is a tool for documenting design tokens usage.</p>
<p>For example:</p>
<ul>
<li><a href="https://storybook.js.org/">Storybook</a></li>
<li><a href="https://zeroheight.com">Zeroheight</a></li>
<li><a href="https://backlight.dev/">Backlight</a></li>
<li><a href="https://www.supernova.io/">Supernova</a></li>
<li><a href="https://www.knapsack.cloud/">Knapsack</a></li>
<li>...</li>
</ul>
</section><section id="type"><div class="header-wrapper"><h3 id="x3-6-type"><bdi class="secno">3.6 </bdi>Type</h3><a class="self-link" href="#type" aria-label="Permalink for Section 3.6"></a></div>
<p>A token's type is a predefined categorization applied to the token's value.</p>
<p>For example:</p>
<ul>
<li>Color</li>
<li>Size</li>
<li>Duration</li>
</ul>
<p>Token tools can use Types to infer the purpose of a token.</p>
<p>For example:</p>
<ul>
<li>A <a data-link-type="dfn|abstract-op" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-3">translation tool</a> might reference a token's type to convert the source value into the correct platform-specific format.</li>
<li>A visual <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-3">design tool</a> might reference type to present tokens in the appropriate part of their UI - as in, color tokens are listed in the color picker, font tokens in the text styling UI's fonts list, and so on.</li>
</ul>
</section><section id="group"><div class="header-wrapper"><h3 id="x3-7-group"><bdi class="secno">3.7 </bdi>Group</h3><a class="self-link" href="#group" aria-label="Permalink for Section 3.7"></a></div>
<p>A group is a set of tokens belonging to a specific category.</p>
<p>For example:</p>
<ul>
<li>Brand</li>
<li>Alert</li>
<li>Layout</li>
</ul>
<p>Groups are arbitrary and tools <em class="rfc2119">SHOULD NOT</em> use them to infer the type or purpose of design tokens.</p>
</section><section id="alias-reference"><div class="header-wrapper"><h3 id="x3-8-alias-reference"><bdi class="secno">3.8 </bdi>Alias (Reference)</h3><a class="self-link" href="#alias-reference" aria-label="Permalink for Section 3.8"></a></div>
<p>A design token's value can be a reference to another token. The same value can have multiple names or <em>aliases</em>.</p>
<p>The following Sass example illustrates this concept:</p>
<pre><code class="scss hljs" aria-busy="false">$color-palette-black: #000000;
$color-text-primary: $color-palette-black;
</code></pre>
<p>The value of <code>$color-text-primary</code> is <code>#000000</code>, because <code>$color-text-primary</code> <em>references <code>$color-palette-black</code></em>. We can also say <code>$color-text-primary</code> is an <em>alias</em> for <code>$color-palette-black.</code></p>
</section><section id="composite-design-token"><div class="header-wrapper"><h3 id="x3-9-composite-design-token"><bdi class="secno">3.9 </bdi>Composite (Design) Token</h3><a class="self-link" href="#composite-design-token" aria-label="Permalink for Section 3.9"></a></div>
<p>A design token whose value is made up of multiple, named child values. Composite tokens are useful for closely related style properties that are always applied together. For example, a typography style might be made up of a font name, font size, line height, and color.</p>
<p>Here's <a href="https://design-tokens.github.io/community-group/format/#example-composite-token-example">an example of a composite shadow token</a>:</p>
<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"shadow-token"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#000000"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</section></section>

    <section id="file-format"><div class="header-wrapper"><h2 id="x4-file-format"><bdi class="secno">4. </bdi>File format</h2><a class="self-link" href="#file-format" aria-label="Permalink for Section 4."></a></div>
<p>Design token files are JSON (<a href="https://www.json.org/">https://www.json.org/</a>) files that adhere to the structure described in this specification.</p>
<p>JSON was chosen as an interchange format on the basis of:</p>
<ul>
<li>Broad support in many programming languages' standard libraries. This is expected to lower barriers to entry for developers writing software that supports design token files.</li>
<li>Current popularity and widespread use. This is expected to lower the learning curve as many people will already be familiar with JSON.</li>
<li>Being text-based (rather than binary) allows hand-editing design token files without needing specialized software other than a basic text editor. It also means the files are somewhat human-readable.</li>
</ul>
<section id="media-type-mime-type"><div class="header-wrapper"><h3 id="x4-1-media-type-mime-type"><bdi class="secno">4.1 </bdi>Media type (MIME type)</h3><a class="self-link" href="#media-type-mime-type" aria-label="Permalink for Section 4.1"></a></div>
<p>When serving design token files via HTTP / HTTPS or in any other scenario where a media type (formerly known as MIME type) needs to be specified, the following MIME type <em class="rfc2119">SHOULD</em> be used for design token files:</p>
<ul>
<li><code>application/design-tokens+json</code></li>
</ul>
<p>However, since every design token file is a valid JSON file, they <em class="rfc2119">MAY</em> be served using the JSON media type: <code>application/json</code>. The above, more specific media type is preferred and <em class="rfc2119">SHOULD</em> be used wherever possible.</p>
<p>Tools that can open design token files <em class="rfc2119">MUST</em> support both media types.</p>
</section><section id="file-extensions"><div class="header-wrapper"><h3 id="x4-2-file-extensions"><bdi class="secno">4.2 </bdi>File extensions</h3><a class="self-link" href="#file-extensions" aria-label="Permalink for Section 4.2"></a></div>
<p>When saving design token files on a local file system, it can be useful to have a distinct file extension as this makes them easier to spot in file browsers. It may also help to associate a file icon and a preferred application for opening those files. The following file extensions are recommended by this spec:</p>
<ul>
<li><code>.tokens</code></li>
<li><code>.tokens.json</code></li>
</ul>
<p>The former is more succinct. However, until this format is widely adopted and supported, the latter might be useful to make design token files open in users' preferred JSON editors.</p>
<p>Tools that can open design token files <em class="rfc2119">MAY</em> filter available files (e.g. in an open file dialog) to only show ones using those extensions. It is recommended to also provide users with a way of opening files that do not use those extensions (e.g. a "show all files" option or similar).</p>
<p>Tools that can save design token files <em class="rfc2119">SHOULD</em> append one of the recommended file extensions to the filename when saving.</p>
<div class="note" id="issue-container-generatedID"><div role="heading" class="ednote-title marker" id="h-ednote" aria-level="4"><span>Editor's note</span><span class="issue-label">: JSON schema</span></div><p class="">
  The group is currently exploring the addition of a JSON Schema to support the spec.
</p></div>

<div class="note" id="issue-container-generatedID-0"><div role="heading" class="ednote-title marker" id="h-ednote-0" aria-level="4"><span>Editor's note</span><span class="issue-label">: JSON file size limitations</span></div><p class="">
  A concern about file size limitations of JSON files was raised by one of the vendors. The working group continues to gather feedback about any limitations the JSON format imposes.
</p></div></section></section>

    <section id="design-token-0"><div class="header-wrapper"><h2 id="x5-design-token"><bdi class="secno">5. </bdi>Design token</h2><a class="self-link" href="#design-token-0" aria-label="Permalink for Section 5."></a></div>
<section id="name-and-value"><div class="header-wrapper"><h3 id="x5-1-name-and-value"><bdi class="secno">5.1 </bdi>Name and value</h3><a class="self-link" href="#name-and-value" aria-label="Permalink for Section 5.1"></a></div>
<aside class="example" id="example-minimal-file-with-single-design-token"><div class="marker">
    <a class="self-link" href="#example-minimal-file-with-single-design-token">Example<bdi> 1</bdi></a><span class="example-title">: Minimal file with single design token</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"token name"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>An object with a <strong><code>$value</code></strong> property is a token. Thus, <code>$value</code> is a reserved word in our spec, meaning you can't have a token whose name is "$value". The parent object's key is the token name.</p>
<p>A token's name <em class="rfc2119">MUST</em> be a valid JSON string as defined in [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc8259" title="The JavaScript Object Notation (JSON) Data Interchange Format">RFC8259</a></cite>].</p>
<p>The example above therefore defines 1 design token with the following properties:</p>
<ul>
<li>Name: "token name"</li>
<li>Type: "color"</li>
<li>Value:<ul>
<li>Color Space: "srgb"</li>
<li>Components: [1, 0, 0]</li>
</ul>
</li>
</ul>
<p>Name and value are both <strong>required</strong>.</p>
<p>Token names are case-sensitive, so the following example with 2 tokens in the same group whose names only differ in case is valid:</p>
<aside class="example" id="example-2"><div class="marker">
    <a class="self-link" href="#example-2">Example<bdi> 2</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"font-size"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">3</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"FONT-SIZE"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">16</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>However, some tools <em class="rfc2119">MAY</em> need to transform names when exporting to other languages or displaying names to the user, so having token names that differ only in case is likely to cause identical and undesirable duplicates in the output. For example, a translation tool that converts these tokens to Sass code would generate problematic output like this:</p>
<aside class="example" id="example-3"><div class="marker">
    <a class="self-link" href="#example-3">Example<bdi> 3</bdi></a>
  </div>

<pre><code class="scss hljs" aria-busy="false">$font-size: 3rem;
$font-size: 16px;

// The 2nd $font-size overrides the 1st one, so the 1st token
// has essentially been lost.
</code></pre>
</aside>

<p>Tools <em class="rfc2119">MAY</em> display a warning when token names differ only by case.</p>
<section id="character-restrictions"><div class="header-wrapper"><h4 id="x5-1-1-character-restrictions"><bdi class="secno">5.1.1 </bdi>Character restrictions</h4><a class="self-link" href="#character-restrictions" aria-label="Permalink for Section 5.1.1"></a></div>
<p>All properties defined by this format are prefixed with the dollar sign (<code>$</code>). This convention will also be used for any new properties introduced by future versions of this spec. Therefore, token and <a href="groups">group</a> names <em class="rfc2119">MUST NOT</em> begin with the <code>$</code> character.</p>
<p>Furthermore, due to the syntax used for <a href="groups#references-and-json-pointer-integration">token aliases</a> the following characters <em class="rfc2119">MUST NOT</em> be used anywhere in a token or group name:</p>
<ul>
<li><code>{</code> (left curly bracket)</li>
<li><code>}</code> (right curly bracket)</li>
<li><code>.</code> (period)</li>
</ul>
</section></section><section id="additional-properties"><div class="header-wrapper"><h3 id="x5-2-additional-properties"><bdi class="secno">5.2 </bdi>Additional properties</h3><a class="self-link" href="#additional-properties" aria-label="Permalink for Section 5.2"></a></div>
<p>While <code>$value</code> is the only required property for a token, a number of additional properties <em class="rfc2119">MAY</em> be added:</p>
<section id="description"><div class="header-wrapper"><h4 id="x5-2-1-description"><bdi class="secno">5.2.1 </bdi>Description</h4><a class="self-link" href="#description" aria-label="Permalink for Section 5.2.1"></a></div>
<p>A plain text description explaining the token's purpose can be provided via the optional <code>$description</code> property. Tools <em class="rfc2119">MAY</em> use the description in various ways.</p>
<p>For example:</p>
<ul>
<li>Style guide generators <em class="rfc2119">MAY</em> display the description text alongside a visual preview of the token</li>
<li>IDEs <em class="rfc2119">MAY</em> display the description as a tooltip for auto-completion (similar to how API docs are displayed)</li>
<li><a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-4">Design tools</a> <em class="rfc2119">MAY</em> display the description as a tooltip or alongside tokens wherever they can be selected</li>
<li>Translation tools <em class="rfc2119">MAY</em> render the description to a source code comment alongside the variable or constant they export.</li>
</ul>
<p>The value of the <code>$description</code> property <em class="rfc2119">MUST</em> be a plain JSON string, for example:</p>
<aside class="example" id="example-4"><div class="marker">
    <a class="self-link" href="#example-4">Example<bdi> 4</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Button background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"The background color for buttons in their normal state."</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="type-0"><div class="header-wrapper"><h4 id="x5-2-2-type"><bdi class="secno">5.2.2 </bdi>Type</h4><a class="self-link" href="#type-0" aria-label="Permalink for Section 5.2.2"></a></div>
<p>Design tokens always have an unambiguous type, so that tools can reliably interpret their value.</p>
<p>A token's type can be specified by the optional <code>$type</code> property. If the <code>$type</code> property is not set on a token, then the token's type <em class="rfc2119">MUST</em> be determined as follows:</p>
<ul>
<li>If the token's value is a reference, then its type is the resolved type of the token being referenced.</li>
<li>Otherwise, if any of the token's parent groups have a <code>$type</code> property, then the token's type is inherited from the closest parent group with a <code>$type</code> property.</li>
<li>Otherwise, if none of the parent groups have a <code>$type</code> property, the token's type cannot be determined and the token <em class="rfc2119">MUST</em> be considered invalid.</li>
</ul>
<p>Tools <em class="rfc2119">MUST NOT</em> attempt to guess the type of a token by inspecting the contents of its value.</p>
<p>The <code>$type</code> property can be set on different levels:</p>
<ul>
<li>at the group level</li>
<li>at the token level</li>
</ul>
<p>The <code>$type</code> property <em class="rfc2119">MUST</em> be a plain JSON string, whose value is one of the values specified in this specification's respective type definitions. The value of <code>$type</code> is case-sensitive.</p>
<p>For example:</p>
<aside class="example" id="example-5"><div class="marker">
    <a class="self-link" href="#example-5">Example<bdi> 5</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Button background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="extensions"><div class="header-wrapper"><h4 id="x5-2-3-extensions"><bdi class="secno">5.2.3 </bdi>Extensions</h4><a class="self-link" href="#extensions" aria-label="Permalink for Section 5.2.3"></a></div>
<p>The optional <strong><code>$extensions</code></strong> property is an object where tools <em class="rfc2119">MAY</em> add proprietary, user-, team- or vendor-specific data to a design token. When doing so, each tool <em class="rfc2119">MUST</em> use a vendor-specific key whose value <em class="rfc2119">MAY</em> be any valid JSON data.</p>
<ul>
<li>The keys <em class="rfc2119">SHOULD</em> be chosen such that they avoid the likelihood of a naming clash with another vendor's data. The <a href="https://en.wikipedia.org/wiki/Reverse_domain_name_notation">reverse domain name notation</a> is recommended for this purpose.</li>
<li>Tools that process design token files <em class="rfc2119">MUST</em> preserve any extension data they do not themselves understand. For example, if a design token contains extension data from tool A and the file containing that data is opened by tool B, then tool B <em class="rfc2119">MUST</em> include the original tool A extension data whenever it saves a new design token file containing that token.</li>
</ul>
<aside class="example" id="example-6"><div class="marker">
    <a class="self-link" href="#example-6">Example<bdi> 6</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Button background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$extensions"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"org.example.tool-a"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">42</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"org.example.tool-b"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"turn-up-to-11"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In order to maintain interoperability between tools that support this format, teams and tools <em class="rfc2119">SHOULD</em> restrict their usage of extension data to optional meta-data that is not crucial to understanding that token's value.</p>
<p>Tool vendors are encouraged to publicly share specifications of their extension data wherever possible. That way other tools can add support for them without needing to reverse engineer the extension data. Popular extensions could also be incorporated as standardized features in future revisions of this specification.</p>
<div class="note" id="issue-container-generatedID-1"><div role="heading" class="ednote-title marker" id="h-ednote-1" aria-level="5"><span>Editor's note</span><span class="issue-label">: Extensions section</span></div><p class="">
  The extensions section is not limited to vendors. All token users can add additional data in this section for their own purposes.
</p></div>

</section><section id="deprecated"><div class="header-wrapper"><h4 id="x5-2-4-deprecated"><bdi class="secno">5.2.4 </bdi>Deprecated</h4><a class="self-link" href="#deprecated" aria-label="Permalink for Section 5.2.4"></a></div>
<p>The <strong><code>$deprecated</code></strong> property <em class="rfc2119">MAY</em> be used to mark a token as deprecated, and optionally explain the reason. Reasons to deprecate tokens include but are not limited to the following:</p>
<ul>
<li>A future update to the design system will remove this token</li>
<li>Removing the token now may break existing support</li>
<li>This token is discouraged from future use</li>
</ul>
<aside class="example" id="example-7"><div class="marker">
    <a class="self-link" href="#example-7">Example<bdi> 7</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Button background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.467</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#777777"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$deprecated"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"Button focus"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.44</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.753</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#70c0ff"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$deprecated"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Please use the border style for active buttons instead."</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<table>
<thead>
<tr>
<th align="left">Value</th>
<th align="left">Explanation</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>true</code></td>
<td align="left">This token is deprecated (no explanation provided).</td>
</tr>
<tr>
<td align="left"><code>String</code></td>
<td align="left">This token is deprecated AND this is an explanation.</td>
</tr>
<tr>
<td align="left"><code>false</code></td>
<td align="left">This token is NOT deprecated (may override group defaults).</td>
</tr>
</tbody></table>
<p>Tool makers <em class="rfc2119">MAY</em> augment the string when it contains aliases such as the one given as an example. A tool could potentially resolve the token, and link to docs, code, or render a visual representation of it and link to the new token inside a UI. For example, “Please use {button.activeBorder} instead“ could be output in JS as:</p>
<aside class="example" id="example-8"><div class="marker">
    <a class="self-link" href="#example-8">Example<bdi> 8</bdi></a>
  </div>

<pre><code class="js hljs" aria-busy="false"><span class="hljs-comment">/**
 * <span class="hljs-doctag">@deprecated</span> Please use {<span class="hljs-doctag">@link</span> file://./my-tokens.js:85 button.activeBorder} instead.
 */</span>
</code></pre>
</aside>

<p>Or</p>
<aside class="example" id="example-9"><div class="marker">
    <a class="self-link" href="#example-9">Example<bdi> 9</bdi></a>
  </div>

<pre><code class="js hljs" aria-busy="false"><span class="hljs-comment">/**
 * <span class="hljs-doctag">@deprecated</span> Please use {<span class="hljs-doctag">@link</span> https://docs.ds/tokens/#button-activeborder button.activeBorder} instead.
 */</span>
</code></pre>
</aside></section></section></section>

    <section id="groups"><div class="header-wrapper"><h2 id="x6-groups"><bdi class="secno">6. </bdi>Groups</h2><a class="self-link" href="#groups" aria-label="Permalink for Section 6."></a></div>
<p>Groups organize design tokens into logical collections and provide a hierarchical structure for token files. Groups are arbitrary and tools <em class="rfc2119">SHOULD NOT</em> use them to infer the type or purpose of design tokens.</p>
<section id="group-structure"><div class="header-wrapper"><h3 id="x6-1-group-structure"><bdi class="secno">6.1 </bdi>Group Structure</h3><a class="self-link" href="#group-structure" aria-label="Permalink for Section 6.1"></a></div>
<p>A group is identified as a JSON object that does NOT contain a <a href="design-token#name-and-value"><code>$value</code></a> property. Groups <em class="rfc2119">MAY</em> contain:</p>
<ul>
<li><strong>Child tokens</strong> - Objects with a <code>$value</code> property</li>
<li><strong>Nested groups</strong> - Objects without a <code>$value</code> property</li>
<li><strong>Group properties</strong> - Properties prefixed with <code>$</code> (e.g., <code>$description</code>, <code>$type</code>)</li>
</ul>
<p><strong>Important:</strong> The presence of a <code>$value</code> property definitively identifies an object as a token. If an object contains both <code>$value</code> and child tokens/groups, this creates an invalid structure where the object cannot be both a token and a group simultaneously. Tools <em class="rfc2119">MUST</em> report this as an error.</p>
</section><section id="root-tokens-in-groups"><div class="header-wrapper"><h3 id="x6-2-root-tokens-in-groups"><bdi class="secno">6.2 </bdi>Root Tokens in Groups</h3><a class="self-link" href="#root-tokens-in-groups" aria-label="Permalink for Section 6.2"></a></div>
<p>Groups <em class="rfc2119">MAY</em> contain a <strong>root token</strong> alongside child tokens and nested groups. A root token provides a base value for the group while allowing for variants or extensions.</p>
<p>Groups support root tokens using the reserved name <code>$root</code> as the token name:</p>
<aside class="example" id="example-root-tokens"><div class="marker">
    <a class="self-link" href="#example-root-tokens">Example<bdi> 10</bdi></a><span class="example-title">: Root tokens</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"accent"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$root"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.867</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#dd0000"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-comment">// {color.accent.$root} resolves to {"colorSpace": "srgb", "components": [0.867, 0, 0], "hex": "#dd0000"} (the root token)</span>
        <span class="hljs-comment">// {color.accent} is an invalid token reference (refers to a group, not a token)</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"light"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.133</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.133</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ff2222"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"dark"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.667</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#aa0000"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p><strong>Rationale:</strong> Using <code>$root</code> as a reserved token name eliminates ambiguity between group references and token references while maintaining clear, explicit syntax. The <code>$</code> prefix prevents naming conflicts with user-defined tokens and aligns with other reserved properties in the specification.</p>
</section><section id="group-properties"><div class="header-wrapper"><h3 id="x6-3-group-properties"><bdi class="secno">6.3 </bdi>Group Properties</h3><a class="self-link" href="#group-properties" aria-label="Permalink for Section 6.3"></a></div>
<p>Groups <em class="rfc2119">MAY</em> include the following properties:</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td><code>$description</code></td>
<td>No</td>
<td>A plain JSON string describing the group's purpose</td>
</tr>
<tr>
<td><code>$type</code></td>
<td>No</td>
<td>Acts as a default type for tokens within the group that do not explicitly declare their own type. Type inheritance applies to nested groups and their tokens unless overridden</td>
</tr>
<tr>
<td><code>$extends</code></td>
<td>No</td>
<td>Inherits tokens and properties from another group. See <a href="#extending-groups">Extending Groups</a> for details</td>
</tr>
<tr>
<td><code>$deprecated</code></td>
<td>No</td>
<td>Marks the group as deprecated. Value can be <code>true</code>, <code>false</code>, or a string explanation</td>
</tr>
<tr>
<td><code>$extensions</code></td>
<td>No</td>
<td>Vendor-specific extensions where tools <em class="rfc2119">MAY</em> add proprietary data</td>
</tr>
</tbody></table>
<aside class="example" id="example-group-description"><div class="marker">
    <a class="self-link" href="#example-group-description">Example<bdi> 11</bdi></a><span class="example-title">: Group description</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"spacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"All spacing-related design tokens organized by usage context"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"margin"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-comment">/* tokens */</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"padding"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-comment">/* tokens */</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<aside class="example" id="example-group-type-inheritance"><div class="marker">
    <a class="self-link" href="#example-group-type-inheritance">Example<bdi> 12</bdi></a><span class="example-title">: Group type inheritance</span>
  </div>



<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.6</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#6699ff"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"semantic"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"success"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#00cc66"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"warning"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"amber"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<section id="deprecated-0"><div class="header-wrapper"><h4 id="x6-3-1-deprecated"><bdi class="secno">6.3.1 </bdi><code>$deprecated</code></h4><a class="self-link" href="#deprecated-0" aria-label="Permalink for Section 6.3.1"></a></div>
<p>Groups <em class="rfc2119">MAY</em> include an optional <code>$deprecated</code> property to mark the entire group as deprecated. This extends to all child tokens within the group unless explicitly overridden.</p>
<table>
<thead>
<tr>
<th>Value</th>
<th>Explanation</th>
</tr>
</thead>
<tbody><tr>
<td><code>true</code></td>
<td>This group is deprecated (no explanation provided)</td>
</tr>
<tr>
<td><code>string</code></td>
<td>This group is deprecated AND this is an explanation</td>
</tr>
<tr>
<td><code>false</code></td>
<td>This group is NOT deprecated (may override parent group defaults)</td>
</tr>
</tbody></table>
</section><section id="extensions-0"><div class="header-wrapper"><h4 id="x6-3-2-extensions"><bdi class="secno">6.3.2 </bdi><code>$extensions</code></h4><a class="self-link" href="#extensions-0" aria-label="Permalink for Section 6.3.2"></a></div>
<p>Groups <em class="rfc2119">MAY</em> include an optional <a href="design-token#extensions"><code>$extensions</code></a> property where tools <em class="rfc2119">MAY</em> add proprietary, user-, team- or vendor-specific data. Each tool <em class="rfc2119">MUST</em> use a vendor-specific key whose value <em class="rfc2119">MAY</em> be any valid JSON data.</p>
</section></section><section id="extending-groups"><div class="header-wrapper"><h3 id="x6-4-extending-groups"><bdi class="secno">6.4 </bdi>Extending Groups</h3><a class="self-link" href="#extending-groups" aria-label="Permalink for Section 6.4"></a></div>
<p>Groups <em class="rfc2119">MAY</em> include an optional <code>$extends</code> property to inherit tokens and properties from another group. <code>$extends</code> <em class="rfc2119">MUST NOT</em> reference a token. The <code>$extends</code> property is syntactic sugar for JSON Schema's <code>$ref</code> keyword and follows the same semantic behavior as defined in [<cite><a class="bibref" data-link-type="biblio" href="#bib-json-schema-2020-12" title="JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12">json-schema-2020-12</a></cite>].</p>
<aside class="example" id="example-group-extension"><div class="marker">
    <a class="self-link" href="#example-group-extension">Example<bdi> 13</bdi></a><span class="example-title">: Group extension</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"button"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"text"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ffffff"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"button-primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{button}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.8</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#cc0066"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<section id="equivalence-to-json-schema-ref"><div class="header-wrapper"><h4 id="x6-4-1-equivalence-to-json-schema-ref"><bdi class="secno">6.4.1 </bdi>Equivalence to JSON Schema <code>$ref</code></h4><a class="self-link" href="#equivalence-to-json-schema-ref" aria-label="Permalink for Section 6.4.1"></a></div>
<p>The <code>$extends</code> property is semantically equivalent to JSON Schema's <code>$ref</code> keyword as specified in [<cite><a class="bibref" data-link-type="biblio" href="#bib-json-schema-2020-12" title="JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12">json-schema-2020-12</a></cite>] and later versions. The following two group definitions are functionally identical:</p>
<p><strong>Using <code>$extends</code> (Design Token syntax):</strong></p>
<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"button-primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{button}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.8</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#cc0066"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"focus"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.2</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.6</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ff3399"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
<p><strong>Using <code>$ref</code> (JSON Schema syntax):</strong></p>
<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"button-primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/button"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.8</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#cc0066"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"focus"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.2</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.6</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ff3399"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</section><section id="reference-resolution-and-evaluation"><div class="header-wrapper"><h4 id="x6-4-2-reference-resolution-and-evaluation"><bdi class="secno">6.4.2 </bdi>Reference Resolution and Evaluation</h4><a class="self-link" href="#reference-resolution-and-evaluation" aria-label="Permalink for Section 6.4.2"></a></div>
<p>Extension resolution follows a straightforward process:</p>
<ol>
<li><strong>Find the target:</strong> Resolve the <code>$extends</code> reference to locate the target group</li>
<li><strong>Copy inherited content:</strong> Start with all tokens and properties from the target group</li>
<li><strong>Apply local overrides:</strong> Replace any inherited tokens/properties where local ones exist at the same path</li>
<li><strong>Add new content:</strong> Include any local tokens/properties that don't exist in the inherited group</li>
</ol>
<p>This creates a new resolved group that combines inherited and local content according to the override rules above.</p>
<div class="note" role="note" id="issue-container-generatedID-2"><div role="heading" class="note-title marker" id="h-note" aria-level="5"><span>Note</span><span class="issue-label">: Implementation</span></div><aside class="">
While this specification references JSON Schema <code>$ref</code> behavior for technical implementation guidance, the user-visible behavior is the straightforward deep merge described above. Tools may implement this merge behavior directly or by leveraging JSON Schema libraries.
</aside></div>

</section><section id="inheritance-semantics"><div class="header-wrapper"><h4 id="x6-4-3-inheritance-semantics"><bdi class="secno">6.4.3 </bdi>Inheritance Semantics</h4><a class="self-link" href="#inheritance-semantics" aria-label="Permalink for Section 6.4.3"></a></div>
<p>Group extension follows <strong>deep merge</strong> behavior where local properties override inherited properties at the same path:</p>
<ol>
<li><strong>Inheritance:</strong> All tokens and properties from the referenced group are inherited (circular references are not allowed)</li>
<li><strong>Override:</strong> Local tokens and properties replace inherited ones with the same path</li>
<li><strong>Addition:</strong> Local tokens and properties with new paths are added alongside inherited ones</li>
</ol>
<p><strong>Override Rules:</strong></p>
<ul>
<li><strong>Same path = override:</strong> If both the inherited group and local group define a token at the same path, the local definition wins</li>
<li><strong>Different paths = merge:</strong> Tokens at different paths coexist in the final result</li>
<li><strong>Complete replacement:</strong> When overriding, the entire token definition is replaced (not merged property-by-property)</li>
</ul>
<aside class="example" id="example-override-example"><div class="marker">
    <a class="self-link" href="#example-override-example">Example<bdi> 14</bdi></a><span class="example-title">: Override example</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"input"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"field"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"width"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">12</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ffffff"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"input-amount"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{input}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"field"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"width"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"100px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// Overrides field.width completely</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p><strong>Result for <code>input-amount</code>:</strong></p>
<table>
<thead>
<tr>
<th align="left">Token</th>
<th align="left">Final Value</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>field.width</code></td>
<td align="left"><code>"100px"</code> (local override wins)</td>
</tr>
<tr>
<td align="left"><code>field.background</code></td>
<td align="left"><code>{"colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff"}</code> (inherited, no local override)</td>
</tr>
</tbody></table>
<p><strong>Multi-level Override Example:</strong></p>
<aside class="example" id="example-multi-level-override"><div class="marker">
    <a class="self-link" href="#example-multi-level-override">Example<bdi> 15</bdi></a><span class="example-title">: Multi-level override</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#blue"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"spacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"16px"</span> <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"extended"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{base}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#red"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// Overrides base.color</span>
    <span class="hljs-attr">"border"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1px solid"</span> <span class="hljs-punctuation">}</span> <span class="hljs-comment">// Adds new token</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p><strong>Result for <code>extended</code>:</strong></p>
<table>
<thead>
<tr>
<th align="left">Token</th>
<th align="left">Final Value</th>
<th align="left">Source</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>color</code></td>
<td align="left"><code>"#red"</code></td>
<td align="left">overridden</td>
</tr>
<tr>
<td align="left"><code>spacing</code></td>
<td align="left"><code>"16px"</code></td>
<td align="left">inherited</td>
</tr>
<tr>
<td align="left"><code>border</code></td>
<td align="left"><code>"1px solid"</code></td>
<td align="left">added</td>
</tr>
</tbody></table>
</section><section id="circular-reference-prevention"><div class="header-wrapper"><h4 id="x6-4-4-circular-reference-prevention"><bdi class="secno">6.4.4 </bdi>Circular Reference Prevention</h4><a class="self-link" href="#circular-reference-prevention" aria-label="Permalink for Section 6.4.4"></a></div>
<p>Groups <em class="rfc2119">MUST NOT</em> create circular inheritance chains. The following patterns are <strong>invalid</strong>:</p>
<aside class="example" id="example-invalid-circular-reference"><div class="marker">
    <a class="self-link" href="#example-invalid-circular-reference">Example<bdi> 16</bdi></a><span class="example-title">: Invalid circular reference</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"button"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#blue"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"border"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1px solid"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{button}"</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// ❌ Invalid: circular reference</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<aside class="example" id="example-another-circular-reference"><div class="marker">
    <a class="self-link" href="#example-another-circular-reference">Example<bdi> 17</bdi></a><span class="example-title">: Another circular reference</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"groupA"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{groupB}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"token"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"valueA"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"groupB"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{groupA}"</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// ❌ Invalid: circular reference</span>
    <span class="hljs-attr">"token"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"valueB"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p><strong>Valid inheritance patterns:</strong></p>
<aside class="example" id="example-valid-inheritance-patterns"><div class="marker">
    <a class="self-link" href="#example-valid-inheritance-patterns">Example<bdi> 18</bdi></a><span class="example-title">: Valid inheritance patterns</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"button"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#blue"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"border"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1px solid"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"button-secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{button}"</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// ✅ Valid: references parent group</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#gray"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"button-large"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{button}"</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// ✅ Valid: siblings can reference same parent</span>
    <span class="hljs-attr">"padding"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"16px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="supported-reference-formats"><div class="header-wrapper"><h4 id="x6-4-5-supported-reference-formats"><bdi class="secno">6.4.5 </bdi>Supported Reference Formats</h4><a class="self-link" href="#supported-reference-formats" aria-label="Permalink for Section 6.4.5"></a></div>
<p><code>$extends</code> supports the same reference formats as <a href="#references-and-json-pointer-integration">design token aliases</a>.</p>
</section><section id="error-conditions"><div class="header-wrapper"><h4 id="x6-4-6-error-conditions"><bdi class="secno">6.4.6 </bdi>Error Conditions</h4><a class="self-link" href="#error-conditions" aria-label="Permalink for Section 6.4.6"></a></div>
<p><code>$extends</code> error handling follows JSON Schema <code>$ref</code> error patterns:</p>
<ul>
<li><strong>Unresolvable references:</strong> When the target group cannot be found</li>
<li><strong>Invalid targets:</strong> When the reference points to a non-group (e.g., a token)</li>
<li><strong>Circular references:</strong> When extension chains create cycles</li>
<li><strong>Constraint violations:</strong> When local properties violate inherited constraints</li>
</ul>
<p>Tools <em class="rfc2119">MUST</em> implement the same error detection and reporting patterns used by JSON Schema validators for <code>$ref</code> resolution.</p>
</section><section id="implementation-guidance"><div class="header-wrapper"><h4 id="x6-4-7-implementation-guidance"><bdi class="secno">6.4.7 </bdi>Implementation Guidance</h4><a class="self-link" href="#implementation-guidance" aria-label="Permalink for Section 6.4.7"></a></div>
<p>Tools implementing design token parsing <em class="rfc2119">MAY</em> choose to:</p>
<ol>
<li><strong>Transform to <code>$ref</code>:</strong> Convert <code>$extends</code> to standard JSON Schema <code>$ref</code> syntax and use existing JSON Schema libraries for validation</li>
<li><strong>Native implementation:</strong> Implement <code>$extends</code> directly using the same algorithms as JSON Schema <code>$ref</code> processing</li>
<li><strong>Hybrid approach:</strong> Use JSON Schema libraries for validation while maintaining design token-specific reference syntax</li>
</ol>
<p>Regardless of implementation approach, the semantic behavior <em class="rfc2119">MUST</em> be equivalent to JSON Schema <code>$ref</code> as specified in JSON Schema 2020-12 or later.</p>
</section><section id="relationship-to-json-schema-specifications"><div class="header-wrapper"><h4 id="x6-4-8-relationship-to-json-schema-specifications"><bdi class="secno">6.4.8 </bdi>Relationship to JSON Schema Specifications</h4><a class="self-link" href="#relationship-to-json-schema-specifications" aria-label="Permalink for Section 6.4.8"></a></div>
<p>This specification defines <code>$extends</code> as syntactic sugar for JSON Schema's <code>$ref</code> keyword, providing design token-specific reference syntax while maintaining equivalent behavior. The deep merge semantics described above align with how JSON Schema 2020-12 handles <code>$ref</code> with sibling properties.</p>
<p>For implementers familiar with JSON Schema, the <code>$extends</code> behavior is equivalent to:</p>
<ul>
<li>Converting <code>"$extends": "{group}"</code> to <code>"$ref": "#/group"</code></li>
<li>Applying JSON Schema 2020-12 <code>$ref</code> resolution with sibling property evaluation</li>
</ul>
<p>Tools implementing this specification <em class="rfc2119">MAY</em> choose to:</p>
<ol>
<li><strong>Transform approach:</strong> Convert <code>$extends</code> to <code>$ref</code> and use JSON Schema libraries</li>
<li><strong>Direct implementation:</strong> Implement the deep merge behavior described above</li>
<li><strong>Hybrid approach:</strong> Use JSON Schema for validation while maintaining design token syntax</li>
</ol>
<p>Regardless of implementation approach, the user-visible behavior <em class="rfc2119">MUST</em> match the deep merge semantics described in this specification.</p>
</section></section><section id="empty-groups"><div class="header-wrapper"><h3 id="x6-5-empty-groups"><bdi class="secno">6.5 </bdi>Empty Groups</h3><a class="self-link" href="#empty-groups" aria-label="Permalink for Section 6.5"></a></div>
<p>Groups <em class="rfc2119">MAY</em> be empty (contain no tokens or nested groups). While they may appear to serve no immediate purpose, they:</p>
<ul>
<li>Cause no harm to processing or validation</li>
<li>Support work-in-progress organization during token development</li>
<li>May contain metadata via group properties (<code>$description</code>, <code>$extensions</code>)</li>
<li>Provide placeholder structure for future token development</li>
</ul>
<aside class="example" id="example-empty-group"><div class="marker">
    <a class="self-link" href="#example-empty-group">Example<bdi> 19</bdi></a><span class="example-title">: Empty group</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"experimental"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Tokens for experimental features - currently empty"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$deprecated"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"This group is being phased out"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<div class="note" role="note" id="issue-container-generatedID-3"><div role="heading" class="note-title marker" id="h-note-0" aria-level="4"><span>Note</span><span class="issue-label">: Token vs Group Ambiguity</span></div><aside class="">
Objects without a <code>$value</code> property are interpreted as groups by definition. This can potentially create ambiguity in cases where a token lacks required properties (such as <code>$value</code> or a determinable type) and might be incorrectly parsed as an empty group. Tools <em class="rfc2119">SHOULD</em> provide clear error messages when an object appears to be an incomplete token rather than an intentional empty group.
</aside></div>

</section><section id="references-and-json-pointer-integration"><div class="header-wrapper"><h3 id="x6-6-references-and-json-pointer-integration"><bdi class="secno">6.6 </bdi>References and JSON Pointer Integration</h3><a class="self-link" href="#references-and-json-pointer-integration" aria-label="Permalink for Section 6.6"></a></div>
<p>The current <a href="#references-and-json-pointer-integration">token reference syntax</a> using curly braces (<code>{group.token}</code>) is maintained for backward compatibility and developer ergonomics. However, tools <em class="rfc2119">MAY</em> also support JSON Pointer notation for advanced use cases.</p>
<section id="current-reference-syntax-recommended"><div class="header-wrapper"><h4 id="x6-6-1-current-reference-syntax-recommended"><bdi class="secno">6.6.1 </bdi>Current Reference Syntax (Recommended)</h4><a class="self-link" href="#current-reference-syntax-recommended" aria-label="Permalink for Section 6.6.1"></a></div>
<aside class="example" id="example-current-reference-syntax"><div class="marker">
    <a class="self-link" href="#example-current-reference-syntax">Example<bdi> 20</bdi></a><span class="example-title">: Current reference syntax</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"alias"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{base}"</span> <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="json-pointer-support"><div class="header-wrapper"><h4 id="x6-6-2-json-pointer-support"><bdi class="secno">6.6.2 </bdi>JSON Pointer Support</h4><a class="self-link" href="#json-pointer-support" aria-label="Permalink for Section 6.6.2"></a></div>
<p>Tools <em class="rfc2119">MUST</em> support JSON Pointer references as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6901" title="JavaScript Object Notation (JSON) Pointer">rfc6901</a></cite>], using the <code>$ref</code> property:</p>
<aside class="example" id="example-json-pointer-references"><div class="marker">
    <a class="self-link" href="#example-json-pointer-references">Example<bdi> 21</bdi></a><span class="example-title">: JSON Pointer references</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"alias"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base"</span> <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section></section><section id="processing-rules"><div class="header-wrapper"><h3 id="x6-7-processing-rules"><bdi class="secno">6.7 </bdi>Processing Rules</h3><a class="self-link" href="#processing-rules" aria-label="Permalink for Section 6.7"></a></div>
<section id="token-resolution-order"><div class="header-wrapper"><h4 id="x6-7-1-token-resolution-order"><bdi class="secno">6.7.1 </bdi>Token Resolution Order</h4><a class="self-link" href="#token-resolution-order" aria-label="Permalink for Section 6.7.1"></a></div>
<p>When processing groups, tools <em class="rfc2119">MUST</em> follow this resolution order:</p>
<ol>
<li><strong>Local tokens</strong> - Direct children with <code>$value</code> properties</li>
<li><strong>Root tokens</strong> - Tokens with <code>$root</code> names</li>
<li><strong>Extended tokens</strong> - Tokens inherited via <code>$extends</code> (if not overridden)</li>
<li><strong>Nested groups</strong> - Process recursively</li>
</ol>
</section><section id="path-construction"><div class="header-wrapper"><h4 id="x6-7-2-path-construction"><bdi class="secno">6.7.2 </bdi>Path Construction</h4><a class="self-link" href="#path-construction" aria-label="Permalink for Section 6.7.2"></a></div>
<p>Token paths are constructed by concatenating group names and token names with periods (<code>.</code>). The reserved token name <code>$root</code> is included in the path to maintain explicit, unambiguous references.</p>
<p>Examples:</p>
<table>
<thead>
<tr>
<th align="left">Location</th>
<th align="left">Path</th>
<th align="left">Notes</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>/color/accent/$root</code></td>
<td align="left"><code>color.accent.$root</code></td>
<td align="left">Token path</td>
</tr>
<tr>
<td align="left"><code>/color/accent/light</code></td>
<td align="left"><code>color.accent.light</code></td>
<td align="left">Token path</td>
</tr>
<tr>
<td align="left"><code>/color/accent</code></td>
<td align="left">—</td>
<td align="left">Invalid for token resolution, valid for groups</td>
</tr>
</tbody></table>
</section><section id="type-inheritance"><div class="header-wrapper"><h4 id="x6-7-3-type-inheritance"><bdi class="secno">6.7.3 </bdi>Type Inheritance</h4><a class="self-link" href="#type-inheritance" aria-label="Permalink for Section 6.7.3"></a></div>
<p>Type resolution follows these rules in order of precedence:</p>
<ol>
<li><strong>Token's explicit <a href="design-token#type"><code>$type</code></a> property</strong> (highest precedence)</li>
<li><strong>Resolved group's <code>$type</code> property</strong> (after extension resolution)</li>
<li><strong>Parent group's <code>$type</code> property</strong> (walking up the hierarchy)</li>
<li><strong>Token is invalid</strong> if no type can be determined</li>
</ol>
<p><strong>Type Resolution with Extensions:</strong>
Since <code>$extends</code> follows JSON Schema <code>$ref</code> semantics, type inheritance behavior is determined by constraint validation rather than explicit merge rules. Local type constraints are evaluated alongside inherited constraints according to JSON Schema validation patterns.</p>
<aside class="example" id="example-type-resolution-with-extensions"><div class="marker">
    <a class="self-link" href="#example-type-resolution-with-extensions">Example<bdi> 22</bdi></a><span class="example-title">: Type resolution with extensions</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"extended"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{base}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// Local constraint</span>
    <span class="hljs-attr">"spacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">16</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In this example, the group <code>extended</code> must satisfy both its local <code>$type: "dimension"</code> constraint and any applicable constraints from the referenced <code>base</code> group, following JSON Schema constraint resolution rules.</p>
</section><section id="circular-reference-detection"><div class="header-wrapper"><h4 id="x6-7-4-circular-reference-detection"><bdi class="secno">6.7.4 </bdi>Circular Reference Detection</h4><a class="self-link" href="#circular-reference-detection" aria-label="Permalink for Section 6.7.4"></a></div>
<p>Tools <em class="rfc2119">MUST</em> detect and throw an error on circular references in:</p>
<ul>
<li>Token <a href="#references-and-json-pointer-integration">aliases</a> (<code>{token}</code> references)</li>
<li>Group extensions (<code>$extends</code> references)</li>
<li>JSON Pointer references (<code>$ref</code> properties, if supported)</li>
</ul>
<p>Circular reference detection for <code>$extends</code> follows the same requirements as JSON Schema <code>$ref</code> circular reference detection. Tools <em class="rfc2119">SHOULD</em> implement the same algorithms used by JSON Schema validators for cycle detection.</p>
<aside class="example" id="example-circular-reference-detection"><div class="marker">
    <a class="self-link" href="#example-circular-reference-detection">Example<bdi> 23</bdi></a><span class="example-title">: Circular reference detection</span>
  </div>

<pre><code class="jsonc hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"a"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{b}"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"b"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{c}"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"c"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{a}"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> <span class="hljs-comment">// Creates circular reference: a → b → c → a</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>Tools <em class="rfc2119">MUST</em> report this as an error affecting groups <code>a</code>, <code>b</code>, and <code>c</code>.</p>
</section></section><section id="migration-and-compatibility"><div class="header-wrapper"><h3 id="x6-8-migration-and-compatibility"><bdi class="secno">6.8 </bdi>Migration and Compatibility</h3><a class="self-link" href="#migration-and-compatibility" aria-label="Permalink for Section 6.8"></a></div>
<p>This specification is designed to be backward compatible with existing design token files. Tools implementing this specification:</p>
<ul>
<li><em class="rfc2119">MUST</em> continue to support existing group syntax</li>
<li><em class="rfc2119">SHOULD</em> provide warnings for deprecated patterns</li>
<li><em class="rfc2119">MAY</em> implement new features incrementally</li>
<li><em class="rfc2119">MUST</em> validate that token names do not conflict with reserved properties</li>
</ul>
</section><section id="examples"><div class="header-wrapper"><h3 id="x6-9-examples"><bdi class="secno">6.9 </bdi>Examples</h3><a class="self-link" href="#examples" aria-label="Permalink for Section 6.9"></a></div>
<section id="basic-group-with-root-token"><div class="header-wrapper"><h4 id="x6-9-1-basic-group-with-root-token"><bdi class="secno">6.9.1 </bdi>Basic Group with Root Token</h4><a class="self-link" href="#basic-group-with-root-token" aria-label="Permalink for Section 6.9.1"></a></div>
<aside class="example" id="example-basic-group-with-root-token"><div class="marker">
    <a class="self-link" href="#example-basic-group-with-root-token">Example<bdi> 24</bdi></a><span class="example-title">: Basic group with root token</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"spacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Base spacing scale"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$root"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">16</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"small"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">8</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"large"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">32</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="group-extension-with-override-example"><div class="header-wrapper"><h4 id="x6-9-2-group-extension-with-override-example"><bdi class="secno">6.9.2 </bdi>Group Extension with Override Example</h4><a class="self-link" href="#group-extension-with-override-example" aria-label="Permalink for Section 6.9.2"></a></div>
<aside class="example" id="example-group-extension-with-override"><div class="marker">
    <a class="self-link" href="#example-group-extension-with-override">Example<bdi> 25</bdi></a><span class="example-title">: Group extension with override</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"input"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"field"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"width"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">100</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"%"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"background"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ffffff"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"input-amount"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{input}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"field"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"width"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">100</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p><strong>Resolved tokens:</strong></p>
<ul>
<li><code>{input-amount.field.width}</code> → <code>{ "value": 100, "unit": "px" }</code> (overridden)</li>
<li><code>{input-amount.field.background}</code> → <code>#ffffff</code> (inherited from input)</li>
</ul>
<p>This demonstrates the key use case where a component extends a base component but overrides specific tokens while inheriting others.</p>
</section><section id="complex-hierarchical-structure"><div class="header-wrapper"><h4 id="x6-9-3-complex-hierarchical-structure"><bdi class="secno">6.9.3 </bdi>Complex Hierarchical Structure</h4><a class="self-link" href="#complex-hierarchical-structure" aria-label="Permalink for Section 6.9.3"></a></div>
<aside class="example" id="example-complex-hierarchical-structure"><div class="marker">
    <a class="self-link" href="#example-complex-hierarchical-structure">Example<bdi> 26</bdi></a><span class="example-title">: Complex hierarchical structure</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Complete color system"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"brand"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$root"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"light"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.2</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.533</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.867</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#3388dd"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"dark"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.267</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.6</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#004499"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"semantic"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$extends"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{color.brand}"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"success"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$root"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
            <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#00cc66"</span>
          <span class="hljs-punctuation">}</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"light"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
            <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.2</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.867</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.533</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#33dd88"</span>
          <span class="hljs-punctuation">}</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"dark"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
            <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.6</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.267</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#009944"</span>
          <span class="hljs-punctuation">}</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"error"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$root"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
            <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.8</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#cc0000"</span>
          <span class="hljs-punctuation">}</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"light"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
            <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.2</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.2</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#ff3333"</span>
          <span class="hljs-punctuation">}</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"dark"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
            <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.6</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
            <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#990000"</span>
          <span class="hljs-punctuation">}</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>This structure creates tokens accessible as:</p>
<table>
<thead>
<tr>
<th align="left">Token Reference</th>
<th align="left">Resolved Value</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>{color.brand.$root}</code></td>
<td align="left"><code>{"colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc"}</code></td>
</tr>
<tr>
<td align="left"><code>{color.brand.light}</code></td>
<td align="left"><code>{"colorSpace": "srgb", "components": [0.2, 0.533, 0.867], "hex": "#3388dd"}</code></td>
</tr>
<tr>
<td align="left"><code>{color.semantic.success.$root}</code></td>
<td align="left"><code>{"colorSpace": "srgb", "components": [0, 0.8, 0.4], "hex": "#00cc66"}</code></td>
</tr>
<tr>
<td align="left"><code>{color.semantic.error.dark}</code></td>
<td align="left"><code>{"colorSpace": "srgb", "components": [0.6, 0, 0], "hex": "#990000"}</code></td>
</tr>
</tbody></table>
</section></section><section id="use-cases"><div class="header-wrapper"><h3 id="x6-10-use-cases"><bdi class="secno">6.10 </bdi>Use-cases</h3><a class="self-link" href="#use-cases" aria-label="Permalink for Section 6.10"></a></div>
<section id="file-authoring-organization"><div class="header-wrapper"><h4 id="x6-10-1-file-authoring-organization"><bdi class="secno">6.10.1 </bdi>File authoring &amp; organization</h4><a class="self-link" href="#file-authoring-organization" aria-label="Permalink for Section 6.10.1"></a></div>
<p>Groups let token file authors better organize their token files. Related tokens can be nested into groups to align with the team's naming conventions and/or mental model. When manually authoring files, using groups is also less verbose than a flat list of tokens with repeating prefixes.</p>
<p>For example:</p>
<aside class="example" id="example-organized-token-groups"><div class="marker">
    <a class="self-link" href="#example-organized-token-groups">Example<bdi> 27</bdi></a><span class="example-title">: Organized token groups</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"brand"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"acid green"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"hot pink"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"typeface"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontFamily"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Comic Sans MS"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Times New Roman"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>...is likely to be more convenient to type and, arguably, easier to read, than:</p>
<aside class="example" id="example-flat-token-structure"><div class="marker">
    <a class="self-link" href="#example-flat-token-structure">Example<bdi> 28</bdi></a><span class="example-title">: Flat token structure</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"brand-color-acid-green"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"brand-color-hot-pink"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"brand-typeface-primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Comic Sans MS"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontFamily"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"brand-typeface-secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Times New Roman"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontFamily"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="gui-tools"><div class="header-wrapper"><h4 id="x6-10-2-gui-tools"><bdi class="secno">6.10.2 </bdi>GUI tools</h4><a class="self-link" href="#gui-tools" aria-label="Permalink for Section 6.10.2"></a></div>
<p>Tools that let users pick or edit tokens via a GUI <em class="rfc2119">MAY</em> use the grouping structure to display a suitable form of progressive disclosure, such as a collapsible tree view.</p>
<figure id="figure-group-progressive-disclosure">
  <img src="./group-progressive-disclosure.png" alt="">
  <figcaption><a class="self-link" href="#figure-group-progressive-disclosure">Figure <bdi class="figno">1</bdi></a> <span class="fig-title">Progressive disclosure groups</span></figcaption>
</figure>

</section><section id="translation-tools"><div class="header-wrapper"><h4 id="x6-10-3-translation-tools"><bdi class="secno">6.10.3 </bdi>Translation tools</h4><a class="self-link" href="#translation-tools" aria-label="Permalink for Section 6.10.3"></a></div>
<p>Token names are not guaranteed to be unique within the same file. The same name can be used in different groups. Also, translation tools <em class="rfc2119">MAY</em> need to export design tokens in a uniquely identifiable way, such as variables in code. Translation tools <em class="rfc2119">SHOULD</em> therefore use design tokens' paths as these <em>are</em> unique within a file.</p>
<p>For example, a <a data-link-type="dfn|abstract-op" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-4">translation tool</a> like <a href="https://amzn.github.io/style-dictionary/">Style Dictionary</a> might use the following design token file:</p>
<aside class="example" id="example-translation-tool-input"><div class="marker">
    <a class="self-link" href="#example-translation-tool-input">Example<bdi> 29</bdi></a><span class="example-title">: Translation tool input</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"brand"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"acid green"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"hot pink"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"typeface"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontFamily"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Comic Sans MS"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Times New Roman"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>...and output it as Sass variables like so by concatenating the path to create variable names:</p>
<aside class="example" id="example-translation-tool-output"><div class="marker">
    <a class="self-link" href="#example-translation-tool-output">Example<bdi> 30</bdi></a><span class="example-title">: Translation tool output</span>
  </div>

<pre><code class="scss hljs" aria-busy="false">$brand-color-acid-green: #00ff66;
$brand-color-hot-pink: #ff00ff;
$brand-typeface-primary: 'Comic Sans MS';
$brand-typeface-secondary: 'Times New Roman';
</code></pre>
</aside></section></section></section>

    <section id="aliases-references"><div class="header-wrapper"><h2 id="x7-aliases-references"><bdi class="secno">7. </bdi>Aliases / References</h2><a class="self-link" href="#aliases-references" aria-label="Permalink for Section 7."></a></div>
<p>Instead of having explicit values, tokens can reference the value of another token. To put it another way, a token can be an alias for another token. This spec considers the terms "alias" and "reference" to be synonyms and uses them interchangeably.</p>
<p>Aliases are useful for:</p>
<ul>
<li>Expressing design choices</li>
<li>Eliminating repetition of values in token files (DRYing up the code)</li>
<li>Creating semantic relationships between tokens</li>
<li>Maintaining consistency across related values</li>
</ul>
<section id="reference-syntax"><div class="header-wrapper"><h3 id="x7-1-reference-syntax"><bdi class="secno">7.1 </bdi>Reference Syntax</h3><a class="self-link" href="#reference-syntax" aria-label="Permalink for Section 7.1"></a></div>
<p>Design tokens support two distinct syntaxes for referencing content within token files:</p>
<section id="curly-brace-syntax-token-references"><div class="header-wrapper"><h4 id="x7-1-1-curly-brace-syntax-token-references"><bdi class="secno">7.1.1 </bdi>Curly Brace Syntax (Token References)</h4><a class="self-link" href="#curly-brace-syntax-token-references" aria-label="Permalink for Section 7.1.1"></a></div>
<p>The curly brace syntax is specifically designed for referencing <strong>complete token values</strong> and always resolves to the <code>$value</code> property of the target token.</p>
<aside class="example" id="example-alias-syntax"><div class="marker">
    <a class="self-link" href="#example-alias-syntax">Example<bdi> 31</bdi></a><span class="example-title">: Alias Syntax</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"colors"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"blue"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"semantic"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{colors.blue}"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In this example, <code>{colors.blue}</code> resolves to the entire color object <code>{"colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc"}</code>.</p>
<p><strong>Important:</strong> Curly brace references can ONLY target complete tokens (objects with <code>$value</code> properties), not individual properties within token values or arbitrary document locations.</p>
</section><section id="json-pointer-syntax-required-support"><div class="header-wrapper"><h4 id="x7-1-2-json-pointer-syntax-required-support"><bdi class="secno">7.1.2 </bdi>JSON Pointer Syntax (Required Support)</h4><a class="self-link" href="#json-pointer-syntax-required-support" aria-label="Permalink for Section 7.1.2"></a></div>
<p>For advanced use cases requiring access to specific properties within token values or other parts of the document structure, tokens <em class="rfc2119">MUST</em> support JSON Pointer notation as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6901" title="JavaScript Object Notation (JSON) Pointer">rfc6901</a></cite>], using the <code>$ref</code> property. Tools implementing this specification <em class="rfc2119">MUST</em> support JSON Pointer syntax.</p>
<aside class="example" id="example-32"><div class="marker">
    <a class="self-link" href="#example-32">Example<bdi> 32</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"colors"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"blue"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"semantic"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/colors/blue/$value"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"primaryHue"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/colors/blue/$value/components/0"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In this example:</p>
<ul>
<li><code>"$ref": "#/colors/blue/$value"</code> is equivalent to <code>"{colors.blue}"</code></li>
<li><code>"$ref": "#/colors/blue/$value/components/0"</code> accesses just the red component (0) of the blue color</li>
</ul>
<p><strong>Key Differences:</strong></p>
<table>
<thead>
<tr>
<th>Aspect</th>
<th>Curly Brace <code>{token}</code></th>
<th>JSON Pointer <code>$ref</code></th>
</tr>
</thead>
<tbody><tr>
<td><strong>Targets</strong></td>
<td>Complete tokens only</td>
<td>Any document location</td>
</tr>
<tr>
<td><strong>Implicit path</strong></td>
<td>Always appends <code>/$value</code></td>
<td>Explicit full path required</td>
</tr>
<tr>
<td><strong>Use case</strong></td>
<td>Token-to-token references</td>
<td>Property-level references</td>
</tr>
<tr>
<td><strong>Syntax</strong></td>
<td><code>{group.token}</code></td>
<td><code>#/group/token/$value</code></td>
</tr>
</tbody></table>
</section></section><section id="reference-resolution"><div class="header-wrapper"><h3 id="x7-2-reference-resolution"><bdi class="secno">7.2 </bdi>Reference Resolution</h3><a class="self-link" href="#reference-resolution" aria-label="Permalink for Section 7.2"></a></div>
<p>When a tool needs the actual value of a token it <em class="rfc2119">MUST</em> resolve the reference - i.e. lookup the token being referenced and fetch its value. Tools <em class="rfc2119">SHOULD</em> preserve references and therefore only resolve them whenever the actual value needs to be retrieved. For instance, in a <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-5">design tool</a>, changes to the value of a token being referenced by aliases <em class="rfc2119">SHOULD</em> be reflected wherever those aliases are being used.</p>
<section id="resolution-algorithms"><div class="header-wrapper"><h4 id="x7-2-1-resolution-algorithms"><bdi class="secno">7.2.1 </bdi>Resolution Algorithms</h4><a class="self-link" href="#resolution-algorithms" aria-label="Permalink for Section 7.2.1"></a></div>
<p><strong>For Curly Brace References:</strong></p>
<ol>
<li><strong>Parse reference:</strong> Extract token path from <code>{group.token}</code></li>
<li><strong>Split path:</strong> Convert to segments <code>["group", "token"]</code></li>
<li><strong>Navigate to token:</strong> Find the target token object</li>
<li><strong>Validate token:</strong> Ensure target has <code>$value</code> property</li>
<li><strong>Return token value:</strong> Extract and return the <code>$value</code> content</li>
<li><strong>Check for cycles:</strong> Maintain stack of resolving references</li>
</ol>
<p><strong>For JSON Pointer References:</strong></p>
<ol>
<li><strong>Parse JSON Pointer:</strong> Extract path segments from <code>#/path/to/target</code></li>
<li><strong>Traverse document:</strong> Navigate through each path segment</li>
<li><strong>Apply JSON Pointer rules:</strong><ul>
<li>Numeric segments in array contexts become array indices</li>
<li>All segments in object contexts become property names</li>
<li>Handle escaped characters (<code>~0</code>, <code>~1</code>)</li>
</ul>
</li>
<li><strong>Validate target:</strong> Ensure the final target exists and is accessible</li>
<li><strong>Return value:</strong> Extract and return the resolved value</li>
</ol>
</section><section id="chained-references"><div class="header-wrapper"><h4 id="x7-2-2-chained-references"><bdi class="secno">7.2.2 </bdi>Chained References</h4><a class="self-link" href="#chained-references" aria-label="Permalink for Section 7.2.2"></a></div>
<p>Aliases <em class="rfc2119">MAY</em> reference other aliases. In this case, tools <em class="rfc2119">MUST</em> follow each reference until they find a token with an explicit value.</p>
<aside class="example" id="example-chained-references"><div class="marker">
    <a class="self-link" href="#example-chained-references">Example<bdi> 33</bdi></a><span class="example-title">: Chained References</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.8</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#0066cc"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"semantic"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"brand"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{base.primary}"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"link"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{semantic.brand}"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In this example, <code>{semantic.link}</code> resolves to the same color value as <code>{base.primary}</code> by following the chain: <code>semantic.link</code> → <code>semantic.brand</code> → <code>base.primary</code>.</p>
</section><section id="circular-references"><div class="header-wrapper"><h4 id="x7-2-3-circular-references"><bdi class="secno">7.2.3 </bdi>Circular References</h4><a class="self-link" href="#circular-references" aria-label="Permalink for Section 7.2.3"></a></div>
<p>References <em class="rfc2119">MUST NOT</em> be circular. If a design token file contains circular references, then the value of all tokens in that chain is unknown and an appropriate error or warning message <em class="rfc2119">SHOULD</em> be displayed to the user.</p>
<aside class="example" id="example-34"><div class="marker">
    <a class="self-link" href="#example-34">Example<bdi> 34</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"a"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{b}"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"b"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{c}"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"c"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{a}"</span> <span class="hljs-punctuation">}</span> <span class="hljs-comment">// Creates circular reference: a → b → c → a</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>Tools <em class="rfc2119">MUST</em> detect and report this as an error affecting all tokens in the circular chain.</p>
</section></section><section id="property-level-references"><div class="header-wrapper"><h3 id="x7-3-property-level-references"><bdi class="secno">7.3 </bdi>Property-Level References</h3><a class="self-link" href="#property-level-references" aria-label="Permalink for Section 7.3"></a></div>
<p>JSON Pointer syntax enables references to specific properties within composite tokens, not just entire token values. This enables fine-grained reuse of token components while maintaining semantic relationships.</p>
<p><strong>Important:</strong> Property-level references require JSON Pointer syntax (<code>$ref</code>) and cannot be expressed using curly brace syntax.</p>
<section id="color-component-references"><div class="header-wrapper"><h4 id="x7-3-1-color-component-references"><bdi class="secno">7.3.1 </bdi>Color Component References</h4><a class="self-link" href="#color-component-references" aria-label="Permalink for Section 7.3.1"></a></div>
<aside class="example" id="example-color-component-references"><div class="marker">
    <a class="self-link" href="#example-color-component-references">Example<bdi> 35</bdi></a><span class="example-title">: Color Component References</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"blue"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.2</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.9</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#3366e6"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"semantic"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-comment">// semantic.primary keeps the same red and green components as base.blue</span>
    <span class="hljs-comment">// but uses a different blue component (0.7)</span>
    <span class="hljs-attr">"primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
          <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/blue/$value/components/0"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
          <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/blue/$value/components/1"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
          <span class="hljs-number">0.7</span>
        <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#3366b3"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-comment">// semantic.secondary keeps the same red and green components as base.blue</span>
    <span class="hljs-comment">// but uses a different blue component (0.5)</span>
    <span class="hljs-attr">"secondary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
          <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/blue/$value/components/0"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
          <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/blue/$value/components/1"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
          <span class="hljs-number">0.5</span>
        <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#336680"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span>
    <span class="hljs-punctuation">}</span>
    <span class="hljs-comment">// Changes to the hue of base.blue will automatically propagate</span>
    <span class="hljs-comment">// to both semantic colors</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="dimension-component-references"><div class="header-wrapper"><h4 id="x7-3-2-dimension-component-references"><bdi class="secno">7.3.2 </bdi>Dimension Component References</h4><a class="self-link" href="#dimension-component-references" aria-label="Permalink for Section 7.3.2"></a></div>
<aside class="example" id="example-dimension-component-references"><div class="marker">
    <a class="self-link" href="#example-dimension-component-references">Example<bdi> 36</bdi></a><span class="example-title">: Dimension Component References</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"spacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">16</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"layout"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"small"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/spacing/$value/value"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"large"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">32</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/spacing/$value/unit"</span> <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In this example:</p>
<ul>
<li><code>layout.small</code> uses the same numeric value as <code>base.spacing</code> (16) but with a different unit (<code>rem</code>)</li>
<li><code>layout.large</code> uses the same unit as <code>base.spacing</code> (<code>px</code>) but with a different numeric value (32)</li>
</ul>
</section><section id="typography-component-references"><div class="header-wrapper"><h4 id="x7-3-3-typography-component-references"><bdi class="secno">7.3.3 </bdi>Typography Component References</h4><a class="self-link" href="#typography-component-references" aria-label="Permalink for Section 7.3.3"></a></div>
<aside class="example" id="example-typography-component-references"><div class="marker">
    <a class="self-link" href="#example-typography-component-references">Example<bdi> 37</bdi></a><span class="example-title">: Typography Component References</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"base"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"text"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"fontFamily"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"Helvetica"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"Arial"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"sans-serif"</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontSize"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">16</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontWeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">400</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"lineHeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.5</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"typography"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"headings"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"h1"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"fontFamily"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/text/$value/fontFamily"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontSize"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">32</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontWeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">700</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"lineHeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/text/$value/lineHeight"</span> <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"typography"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"h2"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"fontFamily"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/text/$value/fontFamily"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontSize"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">24</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontWeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">600</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"lineHeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"$ref"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#/base/text/$value/lineHeight"</span> <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"typography"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p>In this example:</p>
<ul>
<li>Both headings inherit the <code>fontFamily</code> and <code>lineHeight</code> from <code>base.text</code></li>
<li>Each heading defines its own <code>fontSize</code> and <code>fontWeight</code></li>
<li>Changes to the base font family or line height automatically affect all headings</li>
</ul>
</section></section><section id="json-pointer-path-construction-and-resolution"><div class="header-wrapper"><h3 id="x7-4-json-pointer-path-construction-and-resolution"><bdi class="secno">7.4 </bdi>JSON Pointer Path Construction and Resolution</h3><a class="self-link" href="#json-pointer-path-construction-and-resolution" aria-label="Permalink for Section 7.4"></a></div>
<p>JSON Pointer syntax provides direct access to any location within the design token document structure, following standard JSON Pointer rules as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6901" title="JavaScript Object Notation (JSON) Pointer">rfc6901</a></cite>].</p>
<section id="path-construction-rules"><div class="header-wrapper"><h4 id="x7-4-1-path-construction-rules"><bdi class="secno">7.4.1 </bdi>Path Construction Rules</h4><a class="self-link" href="#path-construction-rules" aria-label="Permalink for Section 7.4.1"></a></div>
<ul>
<li><strong>Root reference:</strong> <code>#/</code> (refers to the document root)</li>
<li><strong>Object properties:</strong> <code>/</code> separates each level (e.g., <code>#/group/token/$value</code>)</li>
<li><strong>Array indices:</strong> Numeric indices for array elements (e.g., <code>#/color/$value/components/0</code>)</li>
<li><strong>Special characters:</strong> Must be escaped according to JSON Pointer rules:<ul>
<li><code>~</code> becomes <code>~0</code></li>
<li><code>/</code> becomes <code>~1</code></li>
</ul>
</li>
</ul>
</section><section id="token-value-access-patterns"><div class="header-wrapper"><h4 id="x7-4-2-token-value-access-patterns"><bdi class="secno">7.4.2 </bdi>Token Value Access Patterns</h4><a class="self-link" href="#token-value-access-patterns" aria-label="Permalink for Section 7.4.2"></a></div>
<p>Since design tokens store their values in <code>$value</code> properties, JSON Pointer paths to token values follow a predictable pattern:</p>
<table>
<thead>
<tr>
<th>JSON Pointer</th>
<th>Equivalent Curly Brace Reference</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td><code>#/colors/blue/$value</code></td>
<td><code>{colors.blue}</code></td>
<td>Complete token value</td>
</tr>
<tr>
<td><code>#/colors/blue/$value/hex</code></td>
<td>N/A</td>
<td>Hex property of color</td>
</tr>
<tr>
<td><code>#/colors/blue/$value/components/0</code></td>
<td>N/A</td>
<td>First component of color</td>
</tr>
<tr>
<td><code>#/colors/blue/$type</code></td>
<td>N/A</td>
<td>Token type metadata</td>
</tr>
</tbody></table>
</section><section id="resolution-algorithm-for-json-pointer"><div class="header-wrapper"><h4 id="x7-4-3-resolution-algorithm-for-json-pointer"><bdi class="secno">7.4.3 </bdi>Resolution Algorithm for JSON Pointer</h4><a class="self-link" href="#resolution-algorithm-for-json-pointer" aria-label="Permalink for Section 7.4.3"></a></div>
<ol>
<li><strong>Parse JSON Pointer:</strong> Extract path segments from <code>#/path/to/target</code></li>
<li><strong>Traverse document:</strong> Navigate through each path segment</li>
<li><strong>Apply JSON Pointer rules:</strong><ul>
<li>Numeric segments in array contexts become array indices</li>
<li>All segments in object contexts become property names</li>
<li>Handle escaped characters (<code>~0</code>, <code>~1</code>)</li>
</ul>
</li>
<li><strong>Validate target:</strong> Ensure the final target exists and is accessible</li>
<li><strong>Return value:</strong> Extract and return the resolved value</li>
</ol>
</section><section id="curly-brace-resolution-algorithm"><div class="header-wrapper"><h4 id="x7-4-4-curly-brace-resolution-algorithm"><bdi class="secno">7.4.4 </bdi>Curly Brace Resolution Algorithm</h4><a class="self-link" href="#curly-brace-resolution-algorithm" aria-label="Permalink for Section 7.4.4"></a></div>
<ol>
<li><strong>Parse reference:</strong> Extract token path from <code>{group.token}</code></li>
<li><strong>Split path:</strong> Convert to segments <code>["group", "token"]</code></li>
<li><strong>Navigate to token:</strong> Find the target token object</li>
<li><strong>Validate token:</strong> Ensure target has <code>$value</code> property</li>
<li><strong>Return token value:</strong> Extract and return the <code>$value</code> content</li>
<li><strong>Check for cycles:</strong> Maintain stack of resolving references</li>
</ol>
</section><section id="error-conditions-0"><div class="header-wrapper"><h4 id="x7-4-5-error-conditions"><bdi class="secno">7.4.5 </bdi>Error Conditions</h4><a class="self-link" href="#error-conditions-0" aria-label="Permalink for Section 7.4.5"></a></div>
<p>Tools <em class="rfc2119">MUST</em> report errors for:</p>
<ul>
<li><strong>Invalid syntax:</strong> Malformed curly braces or JSON Pointer syntax</li>
<li><strong>Unresolvable paths:</strong> Target path does not exist in document</li>
<li><strong>Invalid token references:</strong> Curly brace syntax targeting non-tokens</li>
<li><strong>Circular references:</strong> Reference chains that loop back to themselves</li>
<li><strong>Type mismatches:</strong> Referenced value incompatible with expected type</li>
</ul>
</section><section id="path-examples"><div class="header-wrapper"><h4 id="x7-4-6-path-examples"><bdi class="secno">7.4.6 </bdi>Path Examples</h4><a class="self-link" href="#path-examples" aria-label="Permalink for Section 7.4.6"></a></div>
<table>
<thead>
<tr>
<th>Token Path</th>
<th>JSON Pointer</th>
<th>Curly Brace Syntax</th>
</tr>
</thead>
<tbody><tr>
<td>Root token "primary"</td>
<td><code>#/primary</code></td>
<td><code>{primary}</code></td>
</tr>
<tr>
<td>Nested token</td>
<td><code>#/colors/blue</code></td>
<td><code>{colors.blue}</code></td>
</tr>
<tr>
<td>Array element</td>
<td><code>#/color/components/0</code></td>
<td>not supported</td>
</tr>
<tr>
<td>Property with space</td>
<td><code>#/brand colors/primary</code></td>
<td><code>{brand colors.primary}</code></td>
</tr>
<tr>
<td>Property with slash</td>
<td><code>#/my~1group/token</code></td>
<td><code>{my/group.token}</code></td>
</tr>
</tbody></table>
</section></section><section id="implementation-guidance-0"><div class="header-wrapper"><h3 id="x7-5-implementation-guidance"><bdi class="secno">7.5 </bdi>Implementation Guidance</h3><a class="self-link" href="#implementation-guidance-0" aria-label="Permalink for Section 7.5"></a></div>
<section id="for-tool-authors"><div class="header-wrapper"><h4 id="x7-5-1-for-tool-authors"><bdi class="secno">7.5.1 </bdi>For Tool Authors</h4><a class="self-link" href="#for-tool-authors" aria-label="Permalink for Section 7.5.1"></a></div>
<p>Tools implementing design token parsing <em class="rfc2119">MUST</em>:</p>
<ol>
<li><strong>Support curly brace syntax</strong> as the primary reference mechanism for token-to-token references</li>
<li><strong>Support JSON Pointer syntax</strong> for document-level references and property access</li>
<li><strong>Validate reference targets</strong> to ensure they point to valid tokens (for curly brace) or valid document locations (for JSON Pointer)</li>
<li><strong>Resolve references</strong> according to the resolution algorithms defined in this specification (<a href="#resolution-algorithms">Resolution Algorithms</a>)</li>
<li><strong>Detect circular references</strong> before attempting resolution</li>
<li><strong>Preserve references</strong> in memory/storage and resolve only when values are needed</li>
<li><strong>Propagate changes</strong> from referenced tokens to all aliases</li>
</ol>
</section><section id="disambiguation-examples"><div class="header-wrapper"><h4 id="x7-5-2-disambiguation-examples"><bdi class="secno">7.5.2 </bdi>Disambiguation Examples</h4><a class="self-link" href="#disambiguation-examples" aria-label="Permalink for Section 7.5.2"></a></div>
<aside class="example" id="example-38"><div class="marker">
    <a class="self-link" href="#example-38">Example<bdi> 38</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"ambiguous"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">10</span><span class="hljs-punctuation">,</span> <span class="hljs-number">20</span><span class="hljs-punctuation">,</span> <span class="hljs-number">30</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"metadata"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"0"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Info about first item"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"1"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Info about second item"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<p><strong>Clear resolution:</strong></p>
<table>
<thead>
<tr>
<th align="left">Reference</th>
<th align="left">Result</th>
<th align="left">Notes</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>#/ambiguous/data/0</code></td>
<td align="left"><code>10</code></td>
<td align="left">JSON Pointer array index</td>
</tr>
<tr>
<td align="left"><code>{ambiguous.metadata.0}</code></td>
<td align="left"><code>"Info about first item"</code></td>
<td align="left">curly brace object property</td>
</tr>
<tr>
<td align="left"><code>{ambiguous.data.0}</code></td>
<td align="left">Error</td>
<td align="left">curly braces cannot access array indices</td>
</tr>
<tr>
<td align="left"><code>{ambiguous.metadata.2}</code></td>
<td align="left">Error</td>
<td align="left">property "2" doesn't exist</td>
</tr>
</tbody></table>
</section><section id="error-conditions-1"><div class="header-wrapper"><h4 id="x7-5-3-error-conditions"><bdi class="secno">7.5.3 </bdi>Error Conditions</h4><a class="self-link" href="#error-conditions-1" aria-label="Permalink for Section 7.5.3"></a></div>
<p>Tools <em class="rfc2119">MUST</em> report errors for:</p>
<ul>
<li><strong>Invalid reference syntax:</strong> Malformed curly braces or JSON Pointer syntax</li>
<li><strong>Unresolvable references:</strong> Target path does not exist</li>
<li><strong>Circular references:</strong> Reference chains that loop back to themselves</li>
<li><strong>Type mismatches:</strong> Referenced property type incompatible with token type</li>
<li><strong>Invalid property paths:</strong> Attempting to reference non-existent properties</li>
</ul>
</section></section><section id="relationship-to-json-schema"><div class="header-wrapper"><h3 id="x7-6-relationship-to-json-schema"><bdi class="secno">7.6 </bdi>Relationship to JSON Schema</h3><a class="self-link" href="#relationship-to-json-schema" aria-label="Permalink for Section 7.6"></a></div>
<p>The reference syntax defined in this specification provides compatibility with JSON Schema patterns while serving the specific needs of design token authoring:</p>
<ul>
<li><strong>JSON Pointer compatibility:</strong> Direct support for RFC 6901 JSON Pointer notation enables integration with JSON Schema tooling</li>
<li><strong>Design token semantics:</strong> Curly brace references provide token-specific syntax optimized for common token-to-token relationships</li>
<li><strong>Complementary approaches:</strong> Both syntaxes serve different use cases within the design token ecosystem</li>
</ul>
<p><strong>Important:</strong> While JSON Pointer references (<code>$ref</code>) in design tokens follow the same syntax as JSON Schema <code>$ref</code>, curly brace references (<code>{token}</code>) are design token-specific and provide different semantics (automatic <code>$value</code> resolution and token-only targeting) compared to standard JSON Schema references.</p>
<hr>
<p><em>This specification provides a flexible, standards-based approach to token references that balances author ergonomics with technical precision, enabling both simple token aliases and sophisticated property-level relationships.</em></p>
</section></section>

    <section id="types"><div class="header-wrapper"><h2 id="x8-types"><bdi class="secno">8. </bdi>Types</h2><a class="self-link" href="#types" aria-label="Permalink for Section 8."></a></div>
<p>Many tools need to know what kind of value a given token represents to process it sensibly. Translation tools <em class="rfc2119">MAY</em> need to convert or format tokens differently depending on their type. <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-6">Design tools</a> <em class="rfc2119">MAY</em> present the user with different kinds of input when editing tokens of a certain type (such as color picker, slider, text input, etc.). Style guide generators <em class="rfc2119">MAY</em> use different kinds of previews for different types of tokens.</p>
<p>This spec defines a number of design-focused types and every design token <em class="rfc2119">MUST</em> use one of these types. Furthermore, that token's value <em class="rfc2119">MUST</em> then follow rules and syntax for the chosen type as defined by this spec.</p>
<p>A token's type can be set directly by giving it a <code>$type</code> property specifying the chosen type. Alternatively, it can inherit a type from one of its parent groups, or be an alias of a token that has the desired type.</p>
<p>If no explicit type has been set for a token, tools <em class="rfc2119">MUST</em> consider the token invalid and not attempt to infer any other type from the value.</p>
<p>If an explicit type is set, but the value does not match the expected syntax then that token is invalid and an appropriate error <em class="rfc2119">SHOULD</em> be displayed to the user. To put it another way, the <code>$type</code> property is a declaration of what kind of values are permissible for the token. (This is similar to typing in programming languages like Java or TypeScript, where a value not compatible with the declared type causes a compilation error).</p>
<section id="color"><div class="header-wrapper"><h3 id="x8-1-color"><bdi class="secno">8.1 </bdi>Color</h3><a class="self-link" href="#color" aria-label="Permalink for Section 8.1"></a></div>
<p>Represents a color in the UI. For details on how to represent colors, see the <a href="../color">Color</a> module.</p>
</section><section id="dimension"><div class="header-wrapper"><h3 id="x8-2-dimension"><bdi class="secno">8.2 </bdi>Dimension</h3><a class="self-link" href="#dimension" aria-label="Permalink for Section 8.2"></a></div>
<p>Represents an amount of distance in a single dimension in the UI, such as a position, width, height, radius, or thickness. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>dimension</code>. The value <em class="rfc2119">MUST</em> be an object containing a numeric <code>value</code> (integer or floating-point) and <code>unit</code> of measurement (<code>"px"</code> or <code>"rem"</code>).</p>
<table>
<thead>
<tr>
<th align="left">Key</th>
<th align="center">Type</th>
<th align="center">Required</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>value</code></td>
<td align="center"><code>number</code></td>
<td align="center">Y</td>
<td align="left">An integer or floating-point value representing the numeric value.</td>
</tr>
<tr>
<td align="left"><code>unit</code></td>
<td align="center"><code>string</code></td>
<td align="center">Y</td>
<td align="left">Unit of distance. Supported values: <code>"px"</code>, <code>"rem"</code>.</td>
</tr>
</tbody></table>
<p>For example:</p>
<aside class="example" id="example-39"><div class="marker">
    <a class="self-link" href="#example-39">Example<bdi> 39</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"spacing-stack-0"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"spacing-stack-1"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<section id="validation"><div class="header-wrapper"><h4 id="x8-2-1-validation"><bdi class="secno">8.2.1 </bdi>Validation</h4><a class="self-link" href="#validation" aria-label="Permalink for Section 8.2.1"></a></div>
<ul>
<li><code>$value.unit</code> may only be <code>"px"</code> or <code>"rem"</code>.<ul>
<li><strong>px</strong>: Represents an idealized pixel on the viewport. The equivalent in Android is <code>dp</code> and iOS is <code>pt</code>. Translation tools <em class="rfc2119">SHOULD</em> therefore convert to these or other equivalent units as needed.</li>
<li><strong>rem</strong>: Represents a multiple of the system's default font size (which <em class="rfc2119">MAY</em> be configurable by the user). 1rem is 100% of the default font size. The equivalent of 1rem on Android is 16sp. Not all platforms have an equivalent to rem, so translation tools <em class="rfc2119">MAY</em> need to do a lossy conversion to a fixed px size by assuming a default font size (usually 16px) for such platforms.</li>
</ul>
</li>
<li><code>$value.unit</code> is still required even if <code>$value.value</code> is <code>0</code>.</li>
</ul>
</section></section><section id="font-family"><div class="header-wrapper"><h3 id="x8-3-font-family"><bdi class="secno">8.3 </bdi>Font family</h3><a class="self-link" href="#font-family" aria-label="Permalink for Section 8.3"></a></div>
<div class="issue" id="issue-container-number-53"><div role="heading" class="issue-title marker" id="h-issue" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/53"><span class="issue-number">Issue 53</span></a><span class="issue-label">: Type: font family <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Typography+Type+Enhancements%22" style="background-color: rgb(212, 163, 47); color: rgb(0, 0, 0);" aria-label="GitHub label: Typography Type Enhancements">Typography Type Enhancements</a></span></div><div class="">

<p>A naive approach like the one below may be appropriate for the first stage of the specification, but this could be more complicated than it seems due to platform/OS/browser restrictions.</p>
</div></div>

<p>Represents a font name or an array of font names (ordered from most to least preferred). The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>fontFamily</code>. The value <em class="rfc2119">MUST</em> either be a string value containing a single font name or an array of strings, each being a single font name.</p>
<p>For example:</p>
<aside class="example" id="example-40"><div class="marker">
    <a class="self-link" href="#example-40">Example<bdi> 40</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Primary font"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Comic Sans MS"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontFamily"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"Body font"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"Helvetica"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"Arial"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"sans-serif"</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontFamily"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="font-weight"><div class="header-wrapper"><h3 id="x8-4-font-weight"><bdi class="secno">8.4 </bdi>Font weight</h3><a class="self-link" href="#font-weight" aria-label="Permalink for Section 8.4"></a></div>
<p>Represents a font weight. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>fontWeight</code>. The value must either be a number value in the range [1, 1000] or one of the pre-defined string values defined in the table below.</p>


<p>Lower numbers represent lighter weights, and higher numbers represent thicker weights, as per the <a href="https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxistag_wght">OpenType <code>wght</code> tag specification</a>. The pre-defined string values are aliases for specific numeric values. For example <code>100</code>, <code>"thin"</code> and <code>"hairline"</code> are all the exact same value.</p>
<table>
<thead>
<tr>
<th>numeric value</th>
<th>string value aliases</th>
</tr>
</thead>
<tbody><tr>
<td><code>100</code></td>
<td><code>thin</code>, <code>hairline</code></td>
</tr>
<tr>
<td><code>200</code></td>
<td><code>extra-light</code>, <code>ultra-light</code></td>
</tr>
<tr>
<td><code>300</code></td>
<td><code>light</code></td>
</tr>
<tr>
<td><code>400</code></td>
<td><code>normal</code>, <code>regular</code>, <code>book</code></td>
</tr>
<tr>
<td><code>500</code></td>
<td><code>medium</code></td>
</tr>
<tr>
<td><code>600</code></td>
<td><code>semi-bold</code>, <code>demi-bold</code></td>
</tr>
<tr>
<td><code>700</code></td>
<td><code>bold</code></td>
</tr>
<tr>
<td><code>800</code></td>
<td><code>extra-bold</code>, <code>ultra-bold</code></td>
</tr>
<tr>
<td><code>900</code></td>
<td><code>black</code>, <code>heavy</code></td>
</tr>
<tr>
<td><code>950</code></td>
<td><code>extra-black</code>, <code>ultra-black</code></td>
</tr>
</tbody></table>
<p>Number values outside of the [1, 1000] range and any other string values, including ones that differ only in case, are invalid and <em class="rfc2119">MUST</em> be rejected by tools.</p>
<p>Example:</p>
<aside class="example" id="example-41"><div class="marker">
    <a class="self-link" href="#example-41">Example<bdi> 41</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"font-weight-default"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">350</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontWeight"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"font-weight-thick"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"extra-bold"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"fontWeight"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="duration"><div class="header-wrapper"><h3 id="x8-5-duration"><bdi class="secno">8.5 </bdi>Duration</h3><a class="self-link" href="#duration" aria-label="Permalink for Section 8.5"></a></div>
<p>Represents the length of time in milliseconds an animation or animation cycle takes to complete, such as 200 milliseconds. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>duration</code>. The value <em class="rfc2119">MUST</em> be an object containing a numeric <code>value</code> (either integer or floating-point) and a <code>unit</code> of milliseconds (<code>"ms"</code>) or seconds (<code>"s"</code>). A millisecond is a unit of time equal to one thousandth of a second.</p>
<table>
<thead>
<tr>
<th align="left">Key</th>
<th align="center">Type</th>
<th align="center">Required</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>value</code></td>
<td align="center"><code>number</code></td>
<td align="center">Y</td>
<td align="left">An integer or floating-point value representing the numeric value.</td>
</tr>
<tr>
<td align="left"><code>unit</code></td>
<td align="center"><code>string</code></td>
<td align="center">Y</td>
<td align="left">Unit of time. Supported values: <code>"ms"</code> (millisecond), <code>"s"</code>(second).</td>
</tr>
</tbody></table>
<p>For example:</p>
<aside class="example" id="example-42"><div class="marker">
    <a class="self-link" href="#example-42">Example<bdi> 42</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Duration-Quick"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">100</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"ms"</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"duration"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"Duration-Long"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"s"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"duration"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<section id="validation-0"><div class="header-wrapper"><h4 id="x8-5-1-validation"><bdi class="secno">8.5.1 </bdi>Validation</h4><a class="self-link" href="#validation-0" aria-label="Permalink for Section 8.5.1"></a></div>
<ul>
<li><code>$value.unit</code> may only be <code>"ms"</code> or <code>"s"</code></li>
</ul>
</section></section><section id="cubic-bezier"><div class="header-wrapper"><h3 id="x8-6-cubic-bezier"><bdi class="secno">8.6 </bdi>Cubic Bézier</h3><a class="self-link" href="#cubic-bezier" aria-label="Permalink for Section 8.6"></a></div>
<p>Represents how the value of an animated property progresses towards completion over the duration of an animation, effectively creating visual effects such as acceleration, deceleration, and bounce. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>cubicBezier</code>. The value <em class="rfc2119">MUST</em> be an array containing four numbers. These numbers represent two points (P1, P2) with one x coordinate and one y coordinate each [P1x, P1y, P2x, P2y]. The y coordinates of P1 and P2 can be any real number in the range [-∞, ∞], but the x coordinates are restricted to the range [0, 1].</p>
<p>For example:</p>
<aside class="example" id="example-43"><div class="marker">
    <a class="self-link" href="#example-43">Example<bdi> 43</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"Accelerate"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"cubicBezier"</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"Decelerate"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"cubicBezier"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="number"><div class="header-wrapper"><h3 id="x8-7-number"><bdi class="secno">8.7 </bdi>Number</h3><a class="self-link" href="#number" aria-label="Permalink for Section 8.7"></a></div>
<p>Represents a number. Numbers can be positive, negative and have fractions. Example uses for number tokens are <a href="composite-types#gradient">gradient stop positions</a> or unitless line heights. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>number</code>. The value <em class="rfc2119">MUST</em> be a JSON number value.</p>
<aside class="example" id="example-44"><div class="marker">
    <a class="self-link" href="#example-44">Example<bdi> 44</bdi></a>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"line-height-large"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2.3</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section class="informative" id="additional-types"><div class="header-wrapper"><h3 id="x8-8-additional-types"><bdi class="secno">8.8 </bdi>Additional types</h3><a class="self-link" href="#additional-types" aria-label="Permalink for Section 8.8"></a></div><p><em>This section is non-normative.</em></p>


<p>Types still to be documented here are likely to include:</p>
<ul>
<li><strong>Font style:</strong> might be an enum of allowed values like ("normal", "italic"...)</li>
<li><strong>Percentage/ratio:</strong> e.g. for opacity values, relative dimensions, aspect ratios, etc.<ul>
<li>Not 100% sure about this since these are really "just" numbers. An alternative might be that we expand the permitted syntax for the "number" type, so for example "1:2", "50%" and 0.5 are all equivalent. People can then use whichever syntax they like best for a given token.</li>
</ul>
</li>
<li><strong>File:</strong> for assets - might just be a relative file path / URL (or should we let people also express the mime-type?)</li>
</ul>
</section></section>

    <section id="composite-types"><div class="header-wrapper"><h2 id="x9-composite-types"><bdi class="secno">9. </bdi>Composite types</h2><a class="self-link" href="#composite-types" aria-label="Permalink for Section 9."></a></div>
<p>The types defined in the previous chapters such as color and dimension all have singular values. For example, the value of a color token is <em>one</em> color. However, there are other aspects of UI designs that are a combination of multiple values. For instance, a shadow style is a combination of a color, X &amp; Y offsets, a blur radius and a spread radius.</p>
<p>Every shadow style has the exact same parts (color, X &amp; Y offsets, etc.), but their respective values will differ. Furthermore, each part's value (which is also known as a "sub-value") is always of the same type. A shadow's color must always be a <a href="#color">color</a> value, its X offset must always be a <a href="types#dimension">dimension</a> value, and so on. Shadow styles are therefore combinations of values <em>that follow a pre-defined structure</em>. In other words, shadow styles are themselves a type. Types like this are called <strong>composite types</strong>.</p>
<p>Specifically, a composite type has the following characteristics:</p>
<ul>
<li>Its value is an object or array, potentially containing nested objects or arrays, following a pre-defined structure where the properties of the (nested) object(s) or the elements of the (nested) arrays are sub-values.</li>
<li>Sub-values may be explicit values (e.g. <code>color</code> values) or references to other design tokens that have the sub-value's type (e.g. <code>"{some.other.token}"</code>).</li>
</ul>
<section id="array-aliasing-in-composite-types"><div class="header-wrapper"><h3 id="x9-1-array-aliasing-in-composite-types"><bdi class="secno">9.1 </bdi>Array aliasing in composite types</h3><a class="self-link" href="#array-aliasing-in-composite-types" aria-label="Permalink for Section 9.1"></a></div>
<p>When a composite type contains array properties, each element in the array may be either an explicit value or a reference to a token of the appropriate type. References in arrays resolve to single values and do not cause array expansion or flattening. This allows for flexible composition where some array elements are references while others are explicit values.</p>
<p>Array aliasing follows these principles:</p>
<ol>
<li><strong>Single value resolution</strong>: References in arrays always resolve to a single value of the appropriate type, never to arrays themselves.</li>
<li><strong>No flattening</strong>: When referencing an array, the entire referenced array is treated as a single element in the referencing array.</li>
<li><strong>Type safety</strong>: Each array element (explicit or referenced) must conform to the expected sub-value type for that composite type.</li>
<li><strong>Mixed composition</strong>: Arrays may freely mix explicit values and references.</li>
</ol>
<p>For example, a shadow token with an array value can mix references to other shadow tokens with explicit shadow objects:</p>
<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"layered-shadow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
      <span class="hljs-string">"{base.shadow}"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{brand.accent}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">4</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">4</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">8</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">]</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
<p>A design token whose type happens to be a composite type is sometimes also called a composite (design) token. Besides their type, there is nothing special about composite tokens. They can have all the other additional properties like <a href="design-token#description"><code>$description</code></a> or <a href="design-token#extensions"><code>$extensions</code></a>. They can also be referenced by other design tokens.</p>
<aside class="example" id="example-composite-token-example"><div class="marker">
    <a class="self-link" href="#example-composite-token-example">Example<bdi> 45</bdi></a><span class="example-title">: Composite token example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"shadow-token"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#000000"</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<aside class="example" id="example-advanced-composite-token-example"><div class="marker">
    <a class="self-link" href="#example-advanced-composite-token-example">Example<bdi> 46</bdi></a><span class="example-title">: Advanced composite token example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"space"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"small"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"shadow-050"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"hex"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"#000000"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"shadow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"medium"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"A composite token where some sub-values are references to tokens that have the correct type and others are explicit values"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{color.shadow-050}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{space.small}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{space.small}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"component"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"card"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"box-shadow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"$description"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"This token is an alias for the composite token {shadow.medium}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{shadow.medium}"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="groups-versus-composite-tokens"><div class="header-wrapper"><h3 id="x9-2-groups-versus-composite-tokens"><bdi class="secno">9.2 </bdi>Groups versus composite tokens</h3><a class="self-link" href="#groups-versus-composite-tokens" aria-label="Permalink for Section 9.2"></a></div>
<p>At first glance, groups and composite tokens might look very similar. However, they are intended to solve different problems and therefore have some important differences:</p>
<ul>
<li><strong><a href="groups">Groups</a></strong> are for arbitrarily grouping tokens for the purposes of naming and/or organization.<ul>
<li>They impose no rules or restrictions on how many tokens or nested groups you put within them, what they are called, or what the types of the tokens within should be. As such, tools <em class="rfc2119">MUST NOT</em> try to infer any special meaning or typing of tokens based on a group they happen to be in.</li>
<li>Different design systems are likely to group their tokens differently.</li>
<li>You can think of groups as containers that exist "outside" of design tokens.</li>
</ul>
</li>
<li><strong>Composite tokens</strong> are individual design tokens whose values are made up of several sub-values.<ul>
<li>Since they are design tokens, they can be referenced by other design tokens. This is not true for groups.</li>
<li>Their type must be one of the composite types defined in this specification. Therefore their names and types of their sub-values are pre-defined. Adding additional sub-values or setting values that don't have the correct type make the composite token invalid.</li>
<li>Tools <em class="rfc2119">MAY</em> provide specialized functionality for composite tokens. For example, a <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-7">design tool</a> may let the user pick from a list of all available shadow tokens when applying a drop shadow effect to an element.</li>
</ul>
</li>
</ul>
</section><section id="stroke-style"><div class="header-wrapper"><h3 id="x9-3-stroke-style"><bdi class="secno">9.3 </bdi>Stroke style</h3><a class="self-link" href="#stroke-style" aria-label="Permalink for Section 9.3"></a></div>
<p>Represents the style applied to lines or borders. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>strokeStyle</code>. The value <em class="rfc2119">MUST</em> be either:</p>
<ul>
<li>a string value as defined in the corresponding section below, or</li>
<li>an object value as defined in the corresponding section below</li>
</ul>
<div class="issue" id="issue-container-number-98"><div role="heading" class="issue-title marker" id="h-issue-0" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/98"><span class="issue-number">Issue 98</span></a><span class="issue-label">: Stroke style type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Composite+Type+Feedback%22" style="background-color: rgb(238, 240, 235); color: rgb(0, 0, 0);" aria-label="GitHub label: Composite Type Feedback">Composite Type Feedback</a></span></div><div class="">
  Is the current specification for stroke styles fit for purpose? Does it need more sub-values (e.g. equivalents to SVG's <code>stroke-linejoin</code>, <code>stroke-miterlimit</code> and <code>stroke-dashoffset</code> attributes)?
</div></div>

<section id="string-value"><div class="header-wrapper"><h4 id="x9-3-1-string-value"><bdi class="secno">9.3.1 </bdi>String value</h4><a class="self-link" href="#string-value" aria-label="Permalink for Section 9.3.1"></a></div>
<p>String stroke style values <em class="rfc2119">MUST</em> be set to one of the following, pre-defined values:</p>
<ul>
<li><code>solid</code></li>
<li><code>dashed</code></li>
<li><code>dotted</code></li>
<li><code>double</code></li>
<li><code>groove</code></li>
<li><code>ridge</code></li>
<li><code>outset</code></li>
<li><code>inset</code></li>
</ul>
<p>These values have the same meaning as the equivalent <a href="https://drafts.csswg.org/css-backgrounds/#typedef-line-style">"line style" values in CSS</a>. As per the CSS spec, their exact rendering is therefore implementation specific. For example, the length of dashes and gaps in the <code>dashed</code> style may vary between different tools.</p>
<aside class="example" id="example-string-stroke-style-example"><div class="marker">
    <a class="self-link" href="#example-string-stroke-style-example">Example<bdi> 47</bdi></a><span class="example-title">: String stroke style example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"focus-ring-style"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"strokeStyle"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dashed"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="object-value"><div class="header-wrapper"><h4 id="x9-3-2-object-value"><bdi class="secno">9.3.2 </bdi>Object value</h4><a class="self-link" href="#object-value" aria-label="Permalink for Section 9.3.2"></a></div>
<p>Object stroke style values <em class="rfc2119">MUST</em> have the following properties:</p>
<ul>
<li><code>dashArray</code>: An array of <a href="types#dimension">dimension values</a> and/or references to dimension tokens, which specify the lengths of alternating dashes and gaps. Each element in the array must be either an explicit dimension value or a reference to a dimension token. If an odd number of values is provided, then the list of values is repeated to yield an even number of values.</li>
<li><code>lineCap</code>: One of the following pre-defined string values: <code>"round"</code>, <code>"butt"</code> or <code>"square"</code>. These values have the same meaning as those of <a href="https://www.w3.org/TR/SVG11/painting.html#StrokeLinecapProperty">the <code>stroke-linecap</code> attribute in SVG</a>.</li>
</ul>
<aside class="example" id="example-object-stroke-style-example"><div class="marker">
    <a class="self-link" href="#example-object-stroke-style-example">Example<bdi> 48</bdi></a><span class="example-title">: Object stroke style example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"alert-border-style"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"strokeStyle"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"dashArray"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
        <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.25</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"lineCap"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"round"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<aside class="example" id="example-stroke-style-obj-ref"><div class="marker">
    <a class="self-link" href="#example-stroke-style-obj-ref">Example<bdi> 49</bdi></a><span class="example-title">: Object stroke style example using references</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"notification-border-style"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"strokeStyle"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"dashArray"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"{dash-length-medium}"</span><span class="hljs-punctuation">,</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.25</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"lineCap"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"butt"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"mixed-dash-style"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"strokeStyle"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"dashArray"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
        <span class="hljs-string">"{dash-length-long}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-string">"{dash-gap-short}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.125</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-string">"{dash-gap-short}"</span>
      <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"lineCap"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"round"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"dash-length-medium"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">10</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"dash-length-long"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"dash-gap-short"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dimension"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.25</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

</section><section id="fallbacks"><div class="header-wrapper"><h4 id="x9-3-3-fallbacks"><bdi class="secno">9.3.3 </bdi>Fallbacks</h4><a class="self-link" href="#fallbacks" aria-label="Permalink for Section 9.3.3"></a></div>
<p>The string and object values are mutually exclusive means of expressing stroke styles. For example, some of the string values like <code>inset</code> or <code>groove</code> cannot be expressed in terms of a <code>dashArray</code> and <code>lineCap</code> as they require some implementation-specific means of lightening or darkening the <em>color</em> for portions of a border or outline. Conversely, a precisely defined combination of <code>dashArray</code> and <code>lineCap</code> sub-values is not guaranteed to produce the same visual result as the <code>dashed</code> or <code>dotted</code> keywords as they are implementation-specific.</p>
<p>Furthermore, some tools and platforms may not support the full range of stroke styles that design tokens of this type can represent. When displaying or exporting a <code>strokeStyle</code> token whose value they don't natively support, they should therefore fallback to the closest approximation that they do support.</p>
<p>The specifics of how a "closest approximation" is chosen are implementation-specific. However, the following examples illustrate what fallbacks tools <em class="rfc2119">MAY</em> use in some scenarios.</p>
<aside class="example" id="example-fallback-for-object-stroke-style"><div class="marker">
    <a class="self-link" href="#example-fallback-for-object-stroke-style">Example<bdi> 50</bdi></a><span class="example-title">: Fallback for object stroke style</span>
  </div>

<p>CSS does not allow detailed control of the dash pattern or line caps on dashed borders. So, a tool exporting the <code>"notification-border-style"</code> design token from the <a href="#example-stroke-style-obj-ref">example in the previous section</a>, might use the CSS <code>dashed</code> line style as a fallback:</p>
<pre><code class="css hljs" aria-busy="false"><span class="hljs-selector-pseudo">:root</span> {
  <span class="hljs-attr">--notification-border-style</span>: dashed;
}
</code></pre>
</aside>

<aside class="example" id="example-fallback-for-string-stroke-style"><div class="marker">
    <a class="self-link" href="#example-fallback-for-string-stroke-style">Example<bdi> 51</bdi></a><span class="example-title">: Fallback for string stroke style</span>
  </div>

<p>Some <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-8">design tools</a> like Figma don't support inset, outset or double style lines. When a user applies a <code>stroke-style</code> token with those values, such tools might therefore fallback to displaying a solid line instead.</p>
</aside>

</section></section><section id="border"><div class="header-wrapper"><h3 id="x9-4-border"><bdi class="secno">9.4 </bdi>Border</h3><a class="self-link" href="#border" aria-label="Permalink for Section 9.4"></a></div>
<p>Represents a border style. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>border</code>. The value <em class="rfc2119">MUST</em> be an object with the following properties:</p>
<ul>
<li><code>color</code>: The color of the border. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#color">color value</a> or a reference to a color token.</li>
<li><code>width</code>: The width or thickness of the border. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>style</code>: The border's style. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#stroke-style">stroke style value</a> or a reference to a stroke style token.</li>
</ul>
<aside class="example" id="example-border-composite-token-examples"><div class="marker">
    <a class="self-link" href="#example-border-composite-token-examples">Example<bdi> 52</bdi></a><span class="example-title">: Border composite token examples</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"border"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"heavy"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"border"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.218</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.218</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.218</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"width"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">3</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"style"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"solid"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"focusring"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"border"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{color.focusring}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"width"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"style"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"dashArray"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
            <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
            <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.25</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
          <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"lineCap"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"round"</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<div class="issue" id="issue-container-number-99"><div role="heading" class="issue-title marker" id="h-issue-1" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/99"><span class="issue-number">Issue 99</span></a><span class="issue-label">: Border type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Composite+Type+Feedback%22" style="background-color: rgb(238, 240, 235); color: rgb(0, 0, 0);" aria-label="GitHub label: Composite Type Feedback">Composite Type Feedback</a></span></div><div class="">
  Is the current specification for borders fit for purpose? Does it need more sub-values to account for features like outset, border images, multiple borders, etc. that some platforms and <a data-link-type="dfn|abstract-op" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-9">design tools</a> have?
</div></div>

</section><section id="transition"><div class="header-wrapper"><h3 id="x9-5-transition"><bdi class="secno">9.5 </bdi>Transition</h3><a class="self-link" href="#transition" aria-label="Permalink for Section 9.5"></a></div>
<p>Represents a animated transition between two states. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>transition</code>. The value <em class="rfc2119">MUST</em> be an object with the following properties:</p>
<ul>
<li><code>duration</code>: The duration of the transition. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#duration">duration</a> value or a reference to a duration token.</li>
<li><code>delay</code>: The time to wait before the transition begins. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#duration">duration</a> value or a reference to a duration token.</li>
<li><code>timingFunction</code>: The timing function of the transition. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#cubic-bezier">cubic Bézier curve</a> value or a reference to a cubic Bézier curve token.</li>
</ul>
<aside class="example" id="example-transition-composite-token-examples"><div class="marker">
    <a class="self-link" href="#example-transition-composite-token-examples">Example<bdi> 53</bdi></a><span class="example-title">: Transition composite token examples</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"transition"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"emphasis"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"transition"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"duration"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">200</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"ms"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"delay"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"ms"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"timingFunction"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<div class="issue" id="issue-container-number-103"><div role="heading" class="issue-title marker" id="h-issue-2" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/103"><span class="issue-number">Issue 103</span></a><span class="issue-label">: Transition type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Composite+Type+Feedback%22" style="background-color: rgb(238, 240, 235); color: rgb(0, 0, 0);" aria-label="GitHub label: Composite Type Feedback">Composite Type Feedback</a></span></div><div class="">
  Is the current specification for transitions fit for purpose? Are these transitions parameters by themselves useful considering that they don't let you specify what aspect of a UI is being transitioned and what the start and end states are?
</div></div>

</section><section id="shadow"><div class="header-wrapper"><h3 id="x9-6-shadow"><bdi class="secno">9.6 </bdi>Shadow</h3><a class="self-link" href="#shadow" aria-label="Permalink for Section 9.6"></a></div>
<p>Represents a shadow style. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>shadow</code>. The value <em class="rfc2119">MUST</em> be either:</p>
<ul>
<li>a single shadow object with the properties defined below, or</li>
<li>an array of shadow objects and/or references to shadow tokens</li>
</ul>
<p>When the value is an array, each element must be either an explicit shadow object or a reference to another shadow token. References in the array resolve to single shadow objects and do not cause array flattening.</p>
<p>Each shadow object (whether explicit or referenced) <em class="rfc2119">MUST</em> have the following properties:</p>
<ul>
<li><code>color</code>: The color of the shadow. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#color">color value</a> or a reference to a color token.</li>
<li><code>offsetX</code>: The horizontal offset that shadow has from the element it is applied to. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>offsetY</code>: The vertical offset that shadow has from the element it is applied to. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>blur</code>: The blur radius that is applied to the shadow. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>spread</code>: The amount by which to expand or contract the shadow. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>inset</code>: (optional) Whether this shadow is inside the containing shape (“inner shadow”), rather than a “drop shadow” or “box shadow” which is rendered outside the container (default, or <code>false</code>).</li>
</ul>
<aside class="example" id="example-shadow-token-example"><div class="marker">
    <a class="self-link" href="#example-shadow-token-example">Example<bdi> 54</bdi></a><span class="example-title">: Shadow token example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"shadow-token"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.5</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"rem"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"layered-shadow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
    <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.1</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">24</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">22</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.2</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">42.9</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">44</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.3</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">64</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">64</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">]</span>
<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

<span class="hljs-attr">"mixed-reference-shadow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
    <span class="hljs-string">"{base.shadow}"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{brand.accent}"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">4</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-string">"{highlight.shadow}"</span>
  <span class="hljs-punctuation">]</span>
<span class="hljs-punctuation">}</span>
<span class="hljs-attr">"inner-shadow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"shadow"</span><span class="hljs-punctuation">,</span>
  <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"alpha"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"offsetX"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"offsetY"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"blur"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">4</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"spread"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"inset"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<div class="issue closed" id="issue-container-number-100"><div role="heading" class="issue-title marker" id="h-issue-3" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/100"><span class="issue-number">Issue 100</span></a><span class="issue-label">: Shadow type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Composite+Type+Feedback%22" style="background-color: rgb(238, 240, 235); color: rgb(0, 0, 0);" aria-label="GitHub label: Composite Type Feedback">Composite Type Feedback</a></span></div><div class="">
  Is the current specification for shadows fit for purpose? Does it need to support multiple shadows, as some tools and platforms do?
</div></div>

</section><section id="gradient"><div class="header-wrapper"><h3 id="x9-7-gradient"><bdi class="secno">9.7 </bdi>Gradient</h3><a class="self-link" href="#gradient" aria-label="Permalink for Section 9.7"></a></div>
<p>Represents a color gradient. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>gradient</code>. The value <em class="rfc2119">MUST</em> be an array of gradient stop objects and/or references to gradient tokens. Each element in the array must be either an explicit gradient stop object or a reference to a gradient token. References resolve to single gradient objects and do not cause array flattening.</p>
<p>Each gradient stop object (whether explicit or referenced) <em class="rfc2119">MUST</em> have the following structure:</p>
<ul>
<li><code>color</code>: The color value at the stop's position on the gradient. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#color">color value</a> or a reference to a color token.</li>
<li><code>position</code>: The position of the stop along the gradient's axis. The value of this property <em class="rfc2119">MUST</em> be a valid number value or reference to a number token. The number values must be in the range [0, 1], where 0 represents the start position of the gradient's axis and 1 the end position. If a number value outside of that range is given, it <em class="rfc2119">MUST</em> be considered as if it were clamped to the range [0, 1]. For example, a value of 42 should be treated as if it were 1, i.e. the end position of the gradient axis. Similarly, a value of -99 should be treated as if it were 0, i.e. the start position of the gradient axis.</li>
</ul>
<p>If there are no stops at the very beginning or end of the gradient axis (i.e. with <code>position</code> 0 or 1, respectively), then the color from the stop closest to each end should be extended to that end of the axis.</p>
<aside class="example" id="example-gradient-token-example"><div class="marker">
    <a class="self-link" href="#example-gradient-token-example">Example<bdi> 55</bdi></a><span class="example-title">: Gradient token example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"blue-to-red"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"gradient"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">]</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
<p>Describes a gradient that goes from blue to red:</p>
<div style="height: 2rem; background: linear-gradient(90deg, #0000ff, #ff0000);"></div>

</aside>

<aside class="example" id="example-gradient-token-with-omitted-start-stop-example"><div class="marker">
    <a class="self-link" href="#example-gradient-token-with-omitted-start-stop-example">Example<bdi> 56</bdi></a><span class="example-title">: Gradient token with omitted start stop example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"mostly-yellow"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"gradient"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.666</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">]</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
<p>Describes a gradient that is solid yellow for the first 2/3 and then fades to red:</p>
<div style="height: 2rem; background: linear-gradient(90deg, #ffff00 66.6%, #ff0000);"></div>

</aside>

<aside class="example" id="example-gradient-token-using-references-example"><div class="marker">
    <a class="self-link" href="#example-gradient-token-using-references-example">Example<bdi> 57</bdi></a><span class="example-title">: Gradient token using references example</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"brand-primary"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"color"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.4</span><span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"position-end"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"brand-in-the-middle"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"gradient"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{brand-primary}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{position-end}"</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">]</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"gradient-with-references"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"gradient"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
      <span class="hljs-string">"{gradient.start-stop}"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{brand.secondary}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.333</span>
      <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
      <span class="hljs-string">"{gradient.end-stop}"</span>
    <span class="hljs-punctuation">]</span>
  <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>

  <span class="hljs-attr">"gradient"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"start-stop"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"gradient"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
        <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span> <span class="hljs-number">1</span><span class="hljs-punctuation">]</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"end-stop"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"gradient"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
        <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"color"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"colorSpace"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"srgb"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"components"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0</span><span class="hljs-punctuation">]</span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"position"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span>
        <span class="hljs-punctuation">}</span>
      <span class="hljs-punctuation">]</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
<p>Describes a color token called "brand-primary", which is referenced as the mid-point of a gradient is black at either end.</p>
<div style="height: 2rem; background: linear-gradient(90deg, #000000, #00ff66, #000000);"></div>

</aside>

<div class="issue" id="issue-container-number-101"><div role="heading" class="issue-title marker" id="h-issue-4" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/101"><span class="issue-number">Issue 101</span></a><span class="issue-label">: Gradient type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Color+Type+Enhancements%22" style="background-color: rgb(197, 162, 204); color: rgb(0, 0, 0);" aria-label="GitHub label: Color Type Enhancements">Color Type Enhancements</a></span></div><div class="">
  Is the current specification for gradients fit for purpose? Does it need to also specify the type of gradient (.e.g linear, radial, conical, etc.)?
</div></div>

</section><section id="typography"><div class="header-wrapper"><h3 id="x9-8-typography"><bdi class="secno">9.8 </bdi>Typography</h3><a class="self-link" href="#typography" aria-label="Permalink for Section 9.8"></a></div>
<p>Represents a typographic style. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>typography</code>. The value <em class="rfc2119">MUST</em> be an object with the following properties:</p>
<ul>
<li><code>fontFamily</code>: The typography's font. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#font-family">font family value</a> or a reference to a font family token.</li>
<li><code>fontSize</code>: The size of the typography. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>fontWeight</code>: The weight of the typography. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#font-weight">font weight</a> or a reference to a font weight token.</li>
<li><code>letterSpacing</code>: The horizontal spacing between characters. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#dimension">dimension value</a> or a reference to a dimension token.</li>
<li><code>lineHeight</code>: The vertical spacing between lines of typography. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="types#number">number value</a> or a reference to a number token. The number <em class="rfc2119">SHOULD</em> be interpreted as a multiplier of the <code>fontSize</code>.</li>
</ul>
<aside class="example" id="example-typography-composite-token-examples"><div class="marker">
    <a class="self-link" href="#example-typography-composite-token-examples">Example<bdi> 58</bdi></a><span class="example-title">: Typography composite token examples</span>
  </div>

<pre><code class="json hljs" aria-busy="false"><span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"type styles"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"heading-level-1"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"typography"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"fontFamily"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Roboto"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontSize"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">42</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontWeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">700</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"letterSpacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0.1</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"lineHeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1.2</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"microcopy"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
      <span class="hljs-attr">"$type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"typography"</span><span class="hljs-punctuation">,</span>
      <span class="hljs-attr">"$value"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
        <span class="hljs-attr">"fontFamily"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{font.serif}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontSize"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{font.size.smallest}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"fontWeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{font.weight.normal}"</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"letterSpacing"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
          <span class="hljs-attr">"value"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span>
          <span class="hljs-attr">"unit"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"px"</span>
        <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
        <span class="hljs-attr">"lineHeight"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span>
      <span class="hljs-punctuation">}</span>
    <span class="hljs-punctuation">}</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</aside>

<div class="issue" id="issue-container-number-102"><div role="heading" class="issue-title marker" id="h-issue-5" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/102"><span class="issue-number">Issue 102</span></a><span class="issue-label">: Typography type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Typography+Type+Enhancements%22" style="background-color: rgb(212, 163, 47); color: rgb(0, 0, 0);" aria-label="GitHub label: Typography Type Enhancements">Typography Type Enhancements</a></span></div><div class="">

<p>Is the current specification for typography styles fit for purpose? <a href="https://github.com/design-tokens/community-group/pull/86#discussion_r768137006">Should the <code>lineHeight</code> sub-value use a number value, dimension or a new lineHeight type</a>?</p>
</div></div></section></section>

    <section class="appendix" id="issue-summary"><div class="header-wrapper"><h2 id="a-issue-summary"><bdi class="secno">A. </bdi>Issue summary</h2><a class="self-link" href="#issue-summary" aria-label="Permalink for Appendix A."></a></div><ul><li><a href="#issue-container-number-53">Issue 53</a><span style="text-transform: none">: Type: font family</span></li><li><a href="#issue-container-number-98">Issue 98</a><span style="text-transform: none">: Stroke style type feedback</span></li><li><a href="#issue-container-number-99">Issue 99</a><span style="text-transform: none">: Border type feedback</span></li><li><a href="#issue-container-number-103">Issue 103</a><span style="text-transform: none">: Transition type feedback</span></li><li><a href="#issue-container-number-100">Issue 100</a><span style="text-transform: none">: Shadow type feedback</span></li><li><a href="#issue-container-number-101">Issue 101</a><span style="text-transform: none">: Gradient type feedback</span></li><li><a href="#issue-container-number-102">Issue 102</a><span style="text-transform: none">: Typography type feedback</span></li></ul></section>
  

<section id="references" class="appendix"><div class="header-wrapper"><h2 id="b-references"><bdi class="secno">B. </bdi>References</h2><a class="self-link" href="#references" aria-label="Permalink for Appendix B."></a></div><section id="normative-references"><div class="header-wrapper"><h3 id="b-1-normative-references"><bdi class="secno">B.1 </bdi>Normative references</h3><a class="self-link" href="#normative-references" aria-label="Permalink for Appendix B.1"></a></div>
    
    <dl class="bibliography"><dt id="bib-json-schema-2020-12">[json-schema-2020-12]</dt><dd>
      <a href="https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01"><cite>JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12</cite></a>. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis.  Internet Engineering Task Force (IETF). 10 June 2022. Internet-Draft. URL: <a href="https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01">https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01</a>
    </dd><dt id="bib-rfc2119">[RFC2119]</dt><dd>
      <a href="https://www.rfc-editor.org/rfc/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. S. Bradner.  IETF. March 1997. Best Current Practice. URL: <a href="https://www.rfc-editor.org/rfc/rfc2119">https://www.rfc-editor.org/rfc/rfc2119</a>
    </dd><dt id="bib-rfc6901">[rfc6901]</dt><dd>
      <a href="https://www.rfc-editor.org/rfc/rfc6901"><cite>JavaScript Object Notation (JSON) Pointer</cite></a>. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed. IETF. April 2013. Proposed Standard. URL: <a href="https://www.rfc-editor.org/rfc/rfc6901">https://www.rfc-editor.org/rfc/rfc6901</a>
    </dd><dt id="bib-rfc8174">[RFC8174]</dt><dd>
      <a href="https://www.rfc-editor.org/rfc/rfc8174"><cite>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</cite></a>. B. Leiba.  IETF. May 2017. Best Current Practice. URL: <a href="https://www.rfc-editor.org/rfc/rfc8174">https://www.rfc-editor.org/rfc/rfc8174</a>
    </dd><dt id="bib-rfc8259">[RFC8259]</dt><dd>
      <a href="https://www.rfc-editor.org/rfc/rfc8259"><cite>The JavaScript Object Notation (JSON) Data Interchange Format</cite></a>. T. Bray, Ed. IETF. December 2017. Internet Standard. URL: <a href="https://www.rfc-editor.org/rfc/rfc8259">https://www.rfc-editor.org/rfc/rfc8259</a>
    </dd></dl>
  </section></section><p role="navigation" id="back-to-top">
    <a href="#title"><abbr title="Back to Top">↑</abbr></a>
  </p><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-design-tool" aria-label="Links in this document to definition: Design tool">
      <span class="caret"></span>
      <div>
        <a class="self-link" href="#dfn-design-tool" aria-label="Permalink for definition: Design tool. Activate to close this dialog.">Permalink</a>
         
      </div>
      <p><b>Referenced in:</b></p>
      <ul>
    <li>
      <a href="#ref-for-dfn-design-tool-1" title="§ 2. Introduction">§ 2. Introduction</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-2" title="§ 3. Terminology">§ 3. Terminology</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-3" title="§ 3.6 Type">§ 3.6 Type</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-4" title="§ 5.2.1 Description">§ 5.2.1 Description</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-5" title="§ 7.2 Reference Resolution">§ 7.2 Reference Resolution</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-6" title="§ 8. Types">§ 8. Types</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-7" title="§ 9.2 Groups versus composite tokens">§ 9.2 Groups versus composite tokens</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-8" title="§ 9.3.3 Fallbacks">§ 9.3.3 Fallbacks</a> 
    </li><li>
      <a href="#ref-for-dfn-design-tool-9" title="§ 9.4 Border">§ 9.4 Border</a> 
    </li>
  </ul>
    </div><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-translation-tool" aria-label="Links in this document to definition: Translation tool">
      <span class="caret"></span>
      <div>
        <a class="self-link" href="#dfn-translation-tool" aria-label="Permalink for definition: Translation tool. Activate to close this dialog.">Permalink</a>
         
      </div>
      <p><b>Referenced in:</b></p>
      <ul>
    <li>
      <a href="#ref-for-dfn-translation-tool-1" title="§ 2. Introduction">§ 2. Introduction</a> <a href="#ref-for-dfn-translation-tool-2" title="Reference 2">(2)</a> 
    </li><li>
      <a href="#ref-for-dfn-translation-tool-3" title="§ 3.6 Type">§ 3.6 Type</a> 
    </li><li>
      <a href="#ref-for-dfn-translation-tool-4" title="§ 6.10.3 Translation tools">§ 6.10.3 Translation tools</a> 
    </li>
  </ul>
    </div><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-documentation-tool" aria-label="Links in this document to definition: Documentation tool">
      <span class="caret"></span>
      <div>
        <a class="self-link" href="#dfn-documentation-tool" aria-label="Permalink for definition: Documentation tool. Activate to close this dialog.">Permalink</a>
         
      </div>
      <p><b>Referenced in:</b></p>
      <ul>
    <li>
      <a href="#ref-for-dfn-documentation-tool-1" title="§ 2. Introduction">§ 2. Introduction</a> 
    </li>
  </ul>
    </div><script id="respec-highlight-vars">(() => {
// @ts-check

if (document.respec) {
  document.respec.ready.then(setupVarHighlighter);
} else {
  setupVarHighlighter();
}

function setupVarHighlighter() {
  document
    .querySelectorAll("var")
    .forEach(varElem => varElem.addEventListener("click", highlightListener));
}

function highlightListener(ev) {
  ev.stopPropagation();
  const { target: varElem } = ev;
  const hightligtedElems = highlightVars(varElem);
  const resetListener = () => {
    const hlColor = getHighlightColor(varElem);
    hightligtedElems.forEach(el => removeHighlight(el, hlColor));
    [...HL_COLORS.keys()].forEach(key => HL_COLORS.set(key, true));
  };
  if (hightligtedElems.length) {
    document.body.addEventListener("click", resetListener, { once: true });
  }
}

// availability of highlight colors. colors from var.css
const HL_COLORS = new Map([
  ["respec-hl-c1", true],
  ["respec-hl-c2", true],
  ["respec-hl-c3", true],
  ["respec-hl-c4", true],
  ["respec-hl-c5", true],
  ["respec-hl-c6", true],
  ["respec-hl-c7", true],
]);

function getHighlightColor(target) {
  // return current colors if applicable
  const { value } = target.classList;
  const re = /respec-hl-\w+/;
  const activeClass = re.test(value) && value.match(re);
  if (activeClass) return activeClass[0];

  // first color preference
  if (HL_COLORS.get("respec-hl-c1") === true) return "respec-hl-c1";

  // otherwise get some other available color
  return [...HL_COLORS.keys()].find(c => HL_COLORS.get(c)) || "respec-hl-c1";
}

function highlightVars(varElem) {
  const textContent = norm(varElem.textContent);
  const parent = varElem.closest(".algorithm, section");
  const highlightColor = getHighlightColor(varElem);

  const varsToHighlight = [...parent.querySelectorAll("var")].filter(
    el =>
      norm(el.textContent) === textContent &&
      el.closest(".algorithm, section") === parent
  );

  // update availability of highlight color
  const colorStatus = varsToHighlight[0].classList.contains("respec-hl");
  HL_COLORS.set(highlightColor, colorStatus);

  // highlight vars
  if (colorStatus) {
    varsToHighlight.forEach(el => removeHighlight(el, highlightColor));
    return [];
  } else {
    varsToHighlight.forEach(el => addHighlight(el, highlightColor));
  }
  return varsToHighlight;
}

function removeHighlight(el, highlightColor) {
  el.classList.remove("respec-hl", highlightColor);
  // clean up empty class attributes so they don't come in export
  if (!el.classList.length) el.removeAttribute("class");
}

function addHighlight(elem, highlightColor) {
  elem.classList.add("respec-hl", highlightColor);
}

/**
 * Same as `norm` from src/core/utils, but our build process doesn't allow
 * imports in runtime scripts, so duplicated here.
 * @param {string} str
 */
function norm(str) {
  return str.trim().replace(/\s+/g, " ");
}
})()</script><script id="respec-dfn-panel">(() => {
// @ts-check
if (document.respec) {
  document.respec.ready.then(setupPanel);
} else {
  setupPanel();
}

function setupPanel() {
  const listener = panelListener();
  document.body.addEventListener("keydown", listener);
  document.body.addEventListener("click", listener);
}

function panelListener() {
  /** @type {HTMLElement} */
  let panel = null;
  return event => {
    const { target, type } = event;

    if (!(target instanceof HTMLElement)) return;

    // For keys, we only care about Enter key to activate the panel
    // otherwise it's activated via a click.
    if (type === "keydown" && event.key !== "Enter") return;

    const action = deriveAction(event);

    switch (action) {
      case "show": {
        hidePanel(panel);
        /** @type {HTMLElement} */
        const dfn = target.closest("dfn, .index-term");
        panel = document.getElementById(`dfn-panel-for-${dfn.id}`);
        const coords = deriveCoordinates(event);
        displayPanel(dfn, panel, coords);
        break;
      }
      case "dock": {
        panel.style.left = null;
        panel.style.top = null;
        panel.classList.add("docked");
        break;
      }
      case "hide": {
        hidePanel(panel);
        panel = null;
        break;
      }
    }
  };
}

/**
 * @param {MouseEvent|KeyboardEvent} event
 */
function deriveCoordinates(event) {
  const target = /** @type HTMLElement */ (event.target);

  // We prevent synthetic AT clicks from putting
  // the dialog in a weird place. The AT events sometimes
  // lack coordinates, so they have clientX/Y = 0
  const rect = target.getBoundingClientRect();
  if (
    event instanceof MouseEvent &&
    event.clientX >= rect.left &&
    event.clientY >= rect.top
  ) {
    // The event probably happened inside the bounding rect...
    return { x: event.clientX, y: event.clientY };
  }

  // Offset to the middle of the element
  const x = rect.x + rect.width / 2;
  // Placed at the bottom of the element
  const y = rect.y + rect.height;
  return { x, y };
}

/**
 * @param {Event} event
 */
function deriveAction(event) {
  const target = /** @type {HTMLElement} */ (event.target);
  const hitALink = !!target.closest("a");
  if (target.closest("dfn:not([data-cite]), .index-term")) {
    return hitALink ? "none" : "show";
  }
  if (target.closest(".dfn-panel")) {
    if (hitALink) {
      return target.classList.contains("self-link") ? "hide" : "dock";
    }
    const panel = target.closest(".dfn-panel");
    return panel.classList.contains("docked") ? "hide" : "none";
  }
  if (document.querySelector(".dfn-panel:not([hidden])")) {
    return "hide";
  }
  return "none";
}

/**
 * @param {HTMLElement} dfn
 * @param {HTMLElement} panel
 * @param {{ x: number, y: number }} clickPosition
 */
function displayPanel(dfn, panel, { x, y }) {
  panel.hidden = false;
  // distance (px) between edge of panel and the pointing triangle (caret)
  const MARGIN = 20;

  const dfnRects = dfn.getClientRects();
  // Find the `top` offset when the `dfn` can be spread across multiple lines
  let closestTop = 0;
  let minDiff = Infinity;
  for (const rect of dfnRects) {
    const { top, bottom } = rect;
    const diffFromClickY = Math.abs((top + bottom) / 2 - y);
    if (diffFromClickY < minDiff) {
      minDiff = diffFromClickY;
      closestTop = top;
    }
  }

  const top = window.scrollY + closestTop + dfnRects[0].height;
  const left = x - MARGIN;
  panel.style.left = `${left}px`;
  panel.style.top = `${top}px`;

  // Find if the panel is flowing out of the window
  const panelRect = panel.getBoundingClientRect();
  const SCREEN_WIDTH = Math.min(window.innerWidth, window.screen.width);
  if (panelRect.right > SCREEN_WIDTH) {
    const newLeft = Math.max(MARGIN, x + MARGIN - panelRect.width);
    const newCaretOffset = left - newLeft;
    panel.style.left = `${newLeft}px`;
    /** @type {HTMLElement} */
    const caret = panel.querySelector(".caret");
    caret.style.left = `${newCaretOffset}px`;
  }

  // As it's a dialog, we trap focus.
  // TODO: when <dialog> becomes a implemented, we should really
  // use that.
  trapFocus(panel, dfn);
}

/**
 * @param {HTMLElement} panel
 * @param {HTMLElement} dfn
 * @returns
 */
function trapFocus(panel, dfn) {
  /** @type NodeListOf<HTMLAnchorElement> elements */
  const anchors = panel.querySelectorAll("a[href]");
  // No need to trap focus
  if (!anchors.length) return;

  // Move focus to first anchor element
  const first = anchors.item(0);
  first.focus();

  const trapListener = createTrapListener(anchors, panel, dfn);
  panel.addEventListener("keydown", trapListener);

  // Hiding the panel releases the trap
  const mo = new MutationObserver(records => {
    const [record] = records;
    const target = /** @type HTMLElement */ (record.target);
    if (target.hidden) {
      panel.removeEventListener("keydown", trapListener);
      mo.disconnect();
    }
  });
  mo.observe(panel, { attributes: true, attributeFilter: ["hidden"] });
}

/**
 *
 * @param {NodeListOf<HTMLAnchorElement>} anchors
 * @param {HTMLElement} panel
 * @param {HTMLElement} dfn
 * @returns
 */
function createTrapListener(anchors, panel, dfn) {
  const lastIndex = anchors.length - 1;
  let currentIndex = 0;
  return event => {
    switch (event.key) {
      // Hitting "Tab" traps us in a nice loop around elements.
      case "Tab": {
        event.preventDefault();
        currentIndex += event.shiftKey ? -1 : +1;
        if (currentIndex < 0) {
          currentIndex = lastIndex;
        } else if (currentIndex > lastIndex) {
          currentIndex = 0;
        }
        anchors.item(currentIndex).focus();
        break;
      }

      // Hitting "Enter" on an anchor releases the trap.
      case "Enter":
        hidePanel(panel);
        break;

      // Hitting "Escape" returns focus to dfn.
      case "Escape":
        hidePanel(panel);
        dfn.focus();
        return;
    }
  };
}

/** @param {HTMLElement} panel */
function hidePanel(panel) {
  if (!panel) return;
  panel.hidden = true;
  panel.classList.remove("docked");
}
})()</script><script src="https://www.w3.org/scripts/TR/2021/fixup.js"></script></body></html>